# freeopensourcepos/flocafe architecture

> Architecture diagram of the GitHub repository freeopensourcepos/flocafe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freeopensourcepos/flocafe
- Repository: https://github.com/freeopensourcepos/flocafe

## Overview

FloCafe is an offline-first desktop POS for cafés and small restaurants, with browser-accessible POS and separate LAN-served displays. Staff configure the store, manage its catalog and tables, enter and settle orders, and coordinate kitchen work; the local API and SQLite database support these workflows. The README also documents printing, inventory, reporting, staff permissions, backups, and optional Google Drive, WhatsApp, and cloud services. Links among unsampled feature areas follow README capability statements or SOURCE INDEX references; their internal details are not established by the excerpts.

Main entry points: [`main/db.ts`](https://github.com/freeopensourcepos/flocafe/blob/main/main/db.ts) (SQLite and backups), [`main/routes/index.ts`](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/index.ts) (API route registry), [`main/server.ts`](https://github.com/freeopensourcepos/flocafe/blob/main/main/server.ts) (Local API server), [`main/routes/orders.ts`](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/orders.ts) (Order and billing routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Staff experience"]
  node_web_clients["POS and dashboards<br/>[page.tsx]"]
  node_setup["Store setup<br/>[page.tsx]"]
  node_kds_ui["Kitchen display<br/>[page.tsx]"]
  node_server_app["Server App<br/>[server-app.ts]"]
end

subgraph group_api["Local application services"]
  node_api_server["Local API server<br/>[server.ts]"]
  node_routes["API route registry<br/>[index.ts]"]
  node_order_routes["Order and billing routes<br/>[orders.ts]"]
  node_catalog_routes["Catalog routes<br/>[products.ts]"]
  node_admin_routes["Admin and reporting routes<br/>[settings.ts]"]
  node_authorization["Role permissions<br/>[authorization.ts]"]
end

subgraph group_operations["Store operations"]
  node_kitchen["Kitchen coordination<br/>[kds.ts]"]
  node_inventory["Inventory and recipes<br/>[inventory.ts]"]
  node_reporting["Sales reports<br/>[reports.ts]"]
end

subgraph group_data["Local data and recovery"]
  node_database[("SQLite and backups<br/>[db.ts]")]
end

subgraph group_integrations["Print and optional integrations"]
  node_printing["Receipt and kitchen printing<br/>[thermal.ts]"]
  node_drive["Google Drive backup<br/>[google-drive.ts]"]
  node_whatsapp["WhatsApp delivery<br/>[whatsapp.ts]"]
  node_cloud["Cloud sync<br/>[cloud-sync.ts]"]
end

node_staff(("Store staff"))
node_external_services(("External services"))

node_staff -->|"uses"| node_web_clients
node_staff -->|"configures"| node_setup
node_web_clients -.->|"requests"| node_api_server
node_kds_ui -.->|"coordinates"| node_kitchen
node_server_app -.->|"serves alongside"| node_api_server
node_api_server -->|"registers"| node_routes
node_routes -->|"registers"| node_order_routes
node_routes -->|"registers"| node_catalog_routes
node_routes -->|"registers"| node_admin_routes
node_routes -->|"guards with"| node_authorization
node_order_routes -.->|"reads and writes"| node_database
node_catalog_routes -.->|"reads and writes"| node_database
node_admin_routes -.->|"manages"| node_database
node_database -.->|"stores records for"| node_inventory
node_database -.->|"supplies data to"| node_reporting
node_order_routes -.->|"prints receipts"| node_printing
node_order_routes -.->|"delivers bills via"| node_whatsapp
node_api_server -.->|"coordinates"| node_kitchen
node_database -.->|"backs up to"| node_drive
node_external_services -.->|"stores backups"| node_drive
node_external_services -.->|"delivers messages"| node_whatsapp
node_api_server -->|"starts"| node_cloud
node_cloud -.->|"syncs optionally"| node_external_services

click node_web_clients "https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/(dashboard)/pos/page.tsx"
click node_setup "https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/setup/page.tsx"
click node_kds_ui "https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/(dashboard)/kds/page.tsx"
click node_server_app "https://github.com/freeopensourcepos/flocafe/blob/main/main/server-app.ts"
click node_api_server "https://github.com/freeopensourcepos/flocafe/blob/main/main/server.ts"
click node_routes "https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/index.ts"
click node_order_routes "https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/orders.ts"
click node_catalog_routes "https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/products.ts"
click node_admin_routes "https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/settings.ts"
click node_authorization "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/authorization.ts"
click node_database "https://github.com/freeopensourcepos/flocafe/blob/main/main/db.ts"
click node_kitchen "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/kds.ts"
click node_inventory "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/inventory.ts"
click node_reporting "https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/reports.ts"
click node_printing "https://github.com/freeopensourcepos/flocafe/blob/main/main/printers/thermal.ts"
click node_drive "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/google-drive.ts"
click node_whatsapp "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/whatsapp.ts"
click node_cloud "https://github.com/freeopensourcepos/flocafe/blob/main/main/services/cloud-sync.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_clients,node_setup,node_kds_ui,node_server_app toneBlue
class node_api_server,node_routes,node_order_routes,node_catalog_routes,node_admin_routes,node_authorization toneAmber
class node_kitchen,node_inventory,node_reporting toneMint
class node_database toneRose
class node_printing,node_drive,node_whatsapp,node_cloud,node_staff,node_external_services toneIndigo
```

## Components

### Staff experience

- [POS and dashboards](https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/(dashboard)/pos/page.tsx): `frontend/src/app/(dashboard)/pos/page.tsx`
- [Store setup](https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/setup/page.tsx): `frontend/src/app/setup/page.tsx`
- [Kitchen display](https://github.com/freeopensourcepos/flocafe/blob/main/frontend/src/app/(dashboard)/kds/page.tsx): `frontend/src/app/(dashboard)/kds/page.tsx`
- [Server App](https://github.com/freeopensourcepos/flocafe/blob/main/main/server-app.ts): `main/server-app.ts`

### Local application services

- [Local API server](https://github.com/freeopensourcepos/flocafe/blob/main/main/server.ts): `main/server.ts`
- [API route registry](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/index.ts): `main/routes/index.ts`
- [Order and billing routes](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/orders.ts): `main/routes/orders.ts`
- [Catalog routes](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/products.ts): `main/routes/products.ts`
- [Admin and reporting routes](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/settings.ts): `main/routes/settings.ts`
- [Role permissions](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/authorization.ts): `main/services/authorization.ts`

### Store operations

- [Kitchen coordination](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/kds.ts): `main/services/kds.ts`
- [Inventory and recipes](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/inventory.ts): `main/services/inventory.ts`
- [Sales reports](https://github.com/freeopensourcepos/flocafe/blob/main/main/routes/reports.ts): `main/routes/reports.ts`

### Local data and recovery

- [SQLite and backups](https://github.com/freeopensourcepos/flocafe/blob/main/main/db.ts): `main/db.ts`

### Print and optional integrations

- [Receipt and kitchen printing](https://github.com/freeopensourcepos/flocafe/blob/main/main/printers/thermal.ts): `main/printers/thermal.ts`
- [Google Drive backup](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/google-drive.ts): `main/services/google-drive.ts`
- [WhatsApp delivery](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/whatsapp.ts): `main/services/whatsapp.ts`
- [Cloud sync](https://github.com/freeopensourcepos/flocafe/blob/main/main/services/cloud-sync.ts): `main/services/cloud-sync.ts`

### Other components

- **Store staff**
- **External services**

## Connections

- Store staff → POS and dashboards: uses (evidence: `README.md`)
- Store staff → Store setup: configures (evidence: `README.md`)
- POS and dashboards → Local API server: requests
- Kitchen display → Kitchen coordination: coordinates
- Server App → Local API server: serves alongside
- Local API server → API route registry: registers (evidence: `main/server.ts`)
- API route registry → Order and billing routes: registers (evidence: `main/routes/index.ts`)
- API route registry → Catalog routes: registers (evidence: `main/routes/index.ts`)
- API route registry → Admin and reporting routes: registers (evidence: `main/routes/index.ts`)
- API route registry → Role permissions: guards with (evidence: `main/routes/index.ts`)
- Order and billing routes → SQLite and backups: reads and writes
- Catalog routes → SQLite and backups: reads and writes
- Admin and reporting routes → SQLite and backups: manages
- SQLite and backups → Inventory and recipes: stores records for
- SQLite and backups → Sales reports: supplies data to
- Order and billing routes → Receipt and kitchen printing: prints receipts
- Order and billing routes → WhatsApp delivery: delivers bills via
- Local API server → Kitchen coordination: coordinates (evidence: `main/server.ts`)
- SQLite and backups → Google Drive backup: backs up to (evidence: `main/services/google-drive.ts`)
- External services → Google Drive backup: stores backups (evidence: `README.md`)
- External services → WhatsApp delivery: delivers messages (evidence: `README.md`)
- Local API server → Cloud sync: starts (evidence: `main/index.ts`)
- Cloud sync → External services: syncs optionally (evidence: `README.md`)
