FlowPOS — Project Overview
Stack Summary
| Component | Technology | Status |
|---|
| Backend | NestJS & PostgreSQL | Active |
| Frontend (Web) | PWA React (Vite) | Active — primary web interface |
| Landing (Web) | Next.js | Active |
| Database | PostgreSQL — GCP Cloud SQL | Staging & Production instances |
| Frontend (Web) | Next.js (web-app) | On hold |
| Frontend (Desktop) | React Native | To be developed — printer integration and devices |
| Dashboards & Reports | Metabase | Active |
Product Strategy
Retail version is the "ready-to-market" product. Restaurant version is on the horizon.
Recommendation: Focus on dominating a specific niche first. In software, it is much easier (and cheaper) to automate marketing for a specific "persona" than for "everyone."
1. Project Purpose and Architecture
Purpose
FlowPOS is a Point of Sale (POS) and business management system for retail and service businesses. It provides integrated solutions for:
- Sales processing
- Inventory management
- Customer and supplier management
- Electronic invoicing (FEL) — initially targeting Guatemala
- Accounts payable and receivable
- Cash register and multi-location operations
Architecture
- Full-stack monorepo managed with PNPM workspaces
- Multiple applications and shared packages
- Cloud-native deployment on Google Cloud Platform (GCP)
- Multi-tenant via row-level isolation (
business_id on all tenant tables) — see docs/architecture/multi-tenancy-tax-adapter-signup.md
2. Main Applications and Packages
Applications (apps/)
| App | Description |
|---|
| backend | NestJS core API server |
| frontend-pwa | Progressive Web App (Vite + React) — mobile-first, primary user interface |
| landing-page | Next.js marketing website |
| web-app | Next.js admin portal — on hold |
Shared Packages (packages/)
| Package | Purpose |
|---|
| backend/database | PostgreSQL schema and migrations (Kysely ORM) |
| backend/scripts | Utility scripts, including endpoint code generation |
| frontend/addon | Shared code for frontend addons |
| frontend/theme | Theming (Tailwind CSS) and styling |
| global | TypeScript constants, enums, interfaces, types, utilities, validators |
Addons (addons/)
Modular extensions (e.g., ui-personalization-addon) for customization without modifying core code.
| Category | Technologies |
|---|
| Core | TypeScript, Node.js |
| Backend | NestJS, PostgreSQL, Kysely ORM |
| Frontend | Next.js, Vite, React, Tailwind CSS, Chakra UI |
| Monorepo | PNPM workspaces, NVM |
| Deployment | Docker, GCP Cloud Run, Artifact Registry, GitHub Actions |
| Secrets | Doppler |
| Code Quality | Biome, ESLint (parts), EditorConfig |
| Integrations | Firebase (auth, config), SendGrid, Google Maps, PgAdmin (local) |
4. Local Development Setup
- Docker Compose for local PostgreSQL (dev, staging, prod simulation)
- PNPM for dependencies and scripts
- NVM for Node.js version consistency
- Doppler CLI for secrets and
.env management
- Database: Migrations via
packages/backend/database (e.g., pnpm run migration:local:push)
5. Deployment Process and Infrastructure
- Deployments: GitHub Actions to GCP Cloud Run
- Environments: Staging (from
develop), Production (from main)
- Images: Docker images pushed to Google Artifact Registry
- Auth: Workload Identity Federation for GitHub ↔ GCP
- Database: GCP Cloud SQL (staging and production instances)
6. Database Management
- Database: PostgreSQL
- ORM: Kysely (type-safe SQL)
- Schema: Managed in
packages/backend/database with migrations
- Endpoint generation: Update
packages/backend/scripts/src/endpoint/config.json, then run pnpm run generate-endpoint
7. Contribution and Endpoint Addition
- Git workflow:
docs/git/git-workflow.md — feature branches from develop, PRs to develop for staging, release branches for production
- Endpoint scaffolding: Update config JSON, run
pnpm run generate-endpoint from packages/backend/scripts
8. Other Significant Details
| Topic | Details |
|---|
| memory-bank/ | Project context, brief, patterns, progress (team/AI context) |
| i18n | Frontend PWA supports multiple languages |
| FEL | Electronic invoicing (Guatemala) — Tax Adapter pattern for future expansion (Mexico, Colombia, USA) |
| Multi-tenancy | business_id on tenant tables; single shared DB per environment |
| Signup automation | Onboarding flow creates business, location, billing — no separate DB per client |
| Practices | CI/CD, containerization, secure secrets management |
- CURSOR.md — Project context and patterns
- docs/architecture/multi-tenancy-tax-adapter-signup.md — Multi-tenancy, signup automation, Tax Adapter pattern
- docs/git/git-workflow.md — Git workflow
- memory-bank/ — Project brief, tech context, product context