# uaibak/poscore architecture

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

- Interactive diagram: https://gitdiagram.com/uaibak/poscore
- Repository: https://github.com/uaibak/poscore

## Overview

1. **Overall shape**
   - Poscore is a **desktop-only, offline-first POS app** built with **Electron + React + TypeScript**.
   - There is **no cloud backend and no sync layer**; all runtime state lives in a **local SQLite database**.

2. **Process boundaries**
   - The app is split into the standard Electron tiers:
     - **Main process**: application bootstrap, database access, privileged business logic.
     - **Preload layer**: safe bridge between renderer and main.
     - **Renderer**: React UI for the cashier/admin experience.
   - The architecture is intentionally shaped so the renderer does **not** talk to the database directly.

3. **Main process as the application backend**
   - `src/main/main.ts` is the entry point for desktop runtime.
   - `src/main/ipc.ts` wires IPC channels between renderer requests and main-process handlers.
   - `src/main/services/*` contains the core domain operations, including:
     - authentication and security
     - catalog/product/category management
     - sales and receipt handling
     - reporting
     - settings
     - audit logging
   - This is effectively the app’s backend, but it runs locally inside Electron.

4. **Local persistence layer**
   - Database code lives under `src/main/database/`.
   - `schema.ts` defines the Drizzle ORM schema.
   - `db.ts` provides the SQLite connection.
   - `migration.ts` handles first-launch schema creation/migration behavior.
   - `001_initial.sql` is the SQL migration artifact.
   - The database is created in the Electron app user-data directory as `poscore.sqlite`, with the seed CLI using the project directory for local verification.

5. **Business domain modules**
   - The service split reflects the product’s functional boundaries:
     - **auth/security**: login, hashed credentials, role permissions, PIN/password handling
     - **catalog**: products, categories, stock-related master data
     - **sales**: order creation, line items, payments, stock deduction, returns
     - **receipt**: receipt generation and printer-oriented output
     - **reports**: sales/inventory/profit/low-stock outputs and exports
     - **settings**: store, tax, currency, printer, backup configuration
     - **audit**: immutable logging of important actions
   - These modules are the key units to reflect in an architecture diagram.

6. **Primary data flow for POS operations**
   - User interaction starts in the **renderer**.
   - The UI sends actions through the **preload bridge** into **IPC**.
   - Main-process services validate the request, apply permissions, and execute database transactions.
   - Sales flows are particularly important: they persist orders, payments, and inventory changes **inside SQLite transactions** so stock and sales stay consistent.

7. **UI layer**
   - `src/renderer/` contains the React front end.
   - `main.tsx` boots the app, `index.html` is the shell, and `styles/app.css` provides global styling.
   - The UI is designed for point-of-sale usage: keyboard-friendly input, barcode scanner-as-keyboard support, cashier/admin navigation, and screens for sales, inventory, reports, and settings.

8. **Shared contract**
   - `src/shared/types.ts` holds types shared across the Electron boundary.
   - This is the contract layer that keeps IPC payloads, service responses, and UI expectations aligned.

9. **Receipts, reports, and device integration**
   - The app supports local hardware and document outputs rather than remote services.
   - Receipt printing and thermal printer support are handled from the main process side.
   - Reports can be exported to **CSV and PDF**, again generated locally.
   - These capabilities are part of the desktop/runtime boundary, not the renderer-only UI.

10. **Backup and recovery**
   - Settings and service code support **manual backup**, **automatic startup backup**, **restore**, and database export.
   - These features operate on the local SQLite file and reinforce the offline, machine-local deployment model.

11. **Security and audit**
   - Credentials are **PBKDF2-hashed**, with role-based access control for admin/cashier workflows.
   - `audit.ts` records important operational events to the audit log table.
   - Security concerns are centralized in the main-process services rather than spread across the UI.

12. **Tooling and build/runtime pipeline**
   - Development uses **Vite** for the renderer and Electron for the desktop shell.
   - `scripts/start-electron.ts` and `vite.config.ts` support the dev startup flow.
   - `scripts/seed.ts` initializes the local schema and sample data.
   - Production packaging is done with **Electron Builder**, producing desktop installers.

13. **External dependency boundary**
   - The app has effectively **no external runtime services**.
   - The only meaningful runtime dependencies are local: the OS, printer access, the filesystem, and SQLite.
   - That makes the architecture easy to diagram as a single-machine system with a clear UI-to-main-to-database path.

14. **What to emphasize in a diagram**
   - Show a **renderer UI** talking only to a **preload bridge**.
   - Show **IPC** as the boundary into the **main process**.
   - Show main-process **service modules** above the **SQLite/Drizzle persistence layer**.
   - Show side capabilities from main process to **printing**, **exports**, **backup/restore**, and **audit logging**.

Main entry points: [`src/main/ipc.ts`](https://github.com/uaibak/poscore/blob/main/src/main/ipc.ts) (IPC layer), [`src/main/database/db.ts`](https://github.com/uaibak/poscore/blob/main/src/main/database/db.ts) (SQLite DB), [`src/main/services/sales.ts`](https://github.com/uaibak/poscore/blob/main/src/main/services/sales.ts) (Sales), [`src/main/services/audit.ts`](https://github.com/uaibak/poscore/blob/main/src/main/services/audit.ts) (Audit log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop runtime"]
  node_main["Main process<br/>electron entry<br/>[main.ts]"]
  node_ipc["IPC layer<br/>channel wiring<br/>[ipc.ts]"]
  node_preload["Preload bridge<br/>secure bridge<br/>[preload.ts]"]
  node_auth["Auth<br/>login and roles<br/>[auth.ts]"]
  node_security["Security<br/>permissions policy<br/>[security.ts]"]
  node_catalog["Catalog<br/>master data<br/>[catalog.ts]"]
  node_sales["Sales<br/>transaction flow<br/>[sales.ts]"]
  node_receipt["Receipts<br/>print output<br/>[receipt.ts]"]
  node_reports["Reports<br/>analytics export<br/>[reports.ts]"]
  node_settings["Settings<br/>configuration<br/>[settings.ts]"]
  node_audit["Audit log<br/>event record<br/>[audit.ts]"]
  node_db[("SQLite DB<br/>local persistence<br/>[db.ts]")]
  node_schema["Schema<br/>[schema.ts]"]
  node_migration["Migration<br/>[migration.ts]"]
  node_initial_sql["Init SQL<br/>migration artifact<br/>[001_initial.sql]"]
end

subgraph group_ui["Renderer UI"]
  node_renderer["POS UI<br/>react app<br/>[main.tsx]"]
end

subgraph group_data["Shared contract"]
  node_shared["Shared types<br/>contract types<br/>[types.ts]"]
end

subgraph group_tooling["Tooling"]
  node_seed["Seed script<br/>local initializer<br/>[seed.ts]"]
  node_start_electron["Start Electron<br/>dev launcher<br/>[start-electron.ts]"]
  node_vite["Vite config<br/>renderer build<br/>[vite.config.ts]"]
end

node_renderer -->|"UI actions"| node_preload
node_preload -->|"invoke"| node_ipc
node_ipc -->|"dispatch"| node_auth
node_ipc -->|"dispatch"| node_catalog
node_ipc -->|"dispatch"| node_sales
node_ipc -->|"dispatch"| node_receipt
node_ipc -->|"dispatch"| node_reports
node_ipc -->|"dispatch"| node_settings
node_ipc -->|"dispatch"| node_audit
node_auth -->|"policy"| node_security
node_sales -->|"transactions"| node_db
node_catalog -->|"reads/writes"| node_db
node_reports -->|"queries"| node_db
node_settings -->|"store"| node_db
node_audit -->|"append"| node_db
node_receipt -->|"lookup"| node_db
node_db -->|"defined by"| node_schema
node_migration -->|"applies"| node_schema
node_migration -->|"uses"| node_initial_sql
node_seed -->|"bootstraps"| node_migration
node_main -->|"starts"| node_ipc
node_main -->|"opens"| node_db
node_start_electron -->|"launches"| node_main
node_vite -->|"builds"| node_renderer
node_shared -->|"contracts"| node_preload
node_shared -->|"contracts"| node_renderer
node_shared -->|"contracts"| node_ipc
node_sales -->|"emits"| node_receipt
node_sales -->|"records"| node_audit
node_settings -->|"records"| node_audit

click node_main "https://github.com/uaibak/poscore/blob/main/src/main/main.ts"
click node_ipc "https://github.com/uaibak/poscore/blob/main/src/main/ipc.ts"
click node_preload "https://github.com/uaibak/poscore/blob/main/src/preload/preload.ts"
click node_renderer "https://github.com/uaibak/poscore/blob/main/src/renderer/main.tsx"
click node_shared "https://github.com/uaibak/poscore/blob/main/src/shared/types.ts"
click node_auth "https://github.com/uaibak/poscore/blob/main/src/main/services/auth.ts"
click node_security "https://github.com/uaibak/poscore/blob/main/src/main/services/security.ts"
click node_catalog "https://github.com/uaibak/poscore/blob/main/src/main/services/catalog.ts"
click node_sales "https://github.com/uaibak/poscore/blob/main/src/main/services/sales.ts"
click node_receipt "https://github.com/uaibak/poscore/blob/main/src/main/services/receipt.ts"
click node_reports "https://github.com/uaibak/poscore/blob/main/src/main/services/reports.ts"
click node_settings "https://github.com/uaibak/poscore/blob/main/src/main/services/settings.ts"
click node_audit "https://github.com/uaibak/poscore/blob/main/src/main/services/audit.ts"
click node_db "https://github.com/uaibak/poscore/blob/main/src/main/database/db.ts"
click node_schema "https://github.com/uaibak/poscore/blob/main/src/main/database/schema.ts"
click node_migration "https://github.com/uaibak/poscore/blob/main/src/main/database/migration.ts"
click node_initial_sql "https://github.com/uaibak/poscore/blob/main/src/main/database/001_initial.sql"
click node_seed "https://github.com/uaibak/poscore/blob/main/scripts/seed.ts"
click node_start_electron "https://github.com/uaibak/poscore/blob/main/scripts/start-electron.ts"
click node_vite "https://github.com/uaibak/poscore/blob/main/vite.config.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_main,node_ipc,node_preload,node_auth,node_security,node_catalog,node_sales,node_receipt,node_reports,node_settings,node_audit,node_db,node_schema,node_migration,node_initial_sql toneBlue
class node_renderer toneAmber
class node_shared toneMint
class node_seed,node_start_electron,node_vite toneRose
```

## Components

### Desktop runtime

Electron main process, preload bridge, and local persistence

- [Main process](https://github.com/uaibak/poscore/blob/main/src/main/main.ts): electron entry · Desktop runtime entrypoint and bootstrap · `src/main/main.ts`
- [IPC layer](https://github.com/uaibak/poscore/blob/main/src/main/ipc.ts): channel wiring · Bridges renderer requests into main-process handlers · `src/main/ipc.ts`
- [Preload bridge](https://github.com/uaibak/poscore/blob/main/src/preload/preload.ts): secure bridge · Safe API surface exposed to the renderer · `src/preload/preload.ts`
- [Auth](https://github.com/uaibak/poscore/blob/main/src/main/services/auth.ts): login and roles · Credentials, access checks, and user identity · `src/main/services/auth.ts`
- [Security](https://github.com/uaibak/poscore/blob/main/src/main/services/security.ts): permissions policy · Role permissions and sensitive workflow guards · `src/main/services/security.ts`
- [Catalog](https://github.com/uaibak/poscore/blob/main/src/main/services/catalog.ts): master data · Products, categories, and stock-facing records · `src/main/services/catalog.ts`
- [Sales](https://github.com/uaibak/poscore/blob/main/src/main/services/sales.ts): transaction flow · Orders, payments, returns, and inventory updates · `src/main/services/sales.ts`
- [Receipts](https://github.com/uaibak/poscore/blob/main/src/main/services/receipt.ts): print output · Receipt generation and printer-oriented formatting · `src/main/services/receipt.ts`
- [Reports](https://github.com/uaibak/poscore/blob/main/src/main/services/reports.ts): analytics export · Sales and inventory reporting plus CSV/PDF export · `src/main/services/reports.ts`
- [Settings](https://github.com/uaibak/poscore/blob/main/src/main/services/settings.ts): configuration · Store, tax, printer, backup, and locale options · `src/main/services/settings.ts`
- [Audit log](https://github.com/uaibak/poscore/blob/main/src/main/services/audit.ts): event record · Immutable operational event logging · `src/main/services/audit.ts`
- [SQLite DB](https://github.com/uaibak/poscore/blob/main/src/main/database/db.ts): local persistence · SQLite connection and transactional storage · `src/main/database/db.ts`
- [Schema](https://github.com/uaibak/poscore/blob/main/src/main/database/schema.ts): drizzle schema · Table and relation definitions · `src/main/database/schema.ts`
- [Migration](https://github.com/uaibak/poscore/blob/main/src/main/database/migration.ts): startup migration · First-launch schema creation and upgrade flow · `src/main/database/migration.ts`
- [Init SQL](https://github.com/uaibak/poscore/blob/main/src/main/database/001_initial.sql): migration artifact · Initial SQL migration file · `src/main/database/001_initial.sql`

### Renderer UI

React cashier/admin interface

- [POS UI](https://github.com/uaibak/poscore/blob/main/src/renderer/main.tsx): react app · Cashier and admin desktop interface · `src/renderer/main.tsx`

### Shared contract

Types shared across the Electron boundary

- [Shared types](https://github.com/uaibak/poscore/blob/main/src/shared/types.ts): contract types · Common IPC and domain payload definitions · `src/shared/types.ts`

### Tooling

Development and seed workflow

- [Seed script](https://github.com/uaibak/poscore/blob/main/scripts/seed.ts): local initializer · Creates schema and sample data for verification · `scripts/seed.ts`
- [Start Electron](https://github.com/uaibak/poscore/blob/main/scripts/start-electron.ts): dev launcher · Development startup helper for Electron · `scripts/start-electron.ts`
- [Vite config](https://github.com/uaibak/poscore/blob/main/vite.config.ts): renderer build · Renderer development and build configuration · `vite.config.ts`

## Connections

- POS UI → Preload bridge: UI actions · Renderer invokes the safe bridge for app operations
- Preload bridge → IPC layer: invoke · Preload forwards approved calls into IPC
- IPC layer → Auth: dispatch · Main-process handlers route auth requests to services
- IPC layer → Catalog: dispatch · Main-process handlers route catalog requests to services
- IPC layer → Sales: dispatch · Main-process handlers route sales requests to services
- IPC layer → Receipts: dispatch · Main-process handlers route receipt requests to services
- IPC layer → Reports: dispatch · Main-process handlers route reporting requests to services
- IPC layer → Settings: dispatch · Main-process handlers route configuration requests to services
- IPC layer → Audit log: dispatch · Main-process handlers route audit writes to services
- Auth → Security: policy · Authentication feeds role and permission enforcement
- Sales → SQLite DB: transactions · Sales work executes in SQLite transactions
- Catalog → SQLite DB: reads/writes · Master data is persisted locally
- Reports → SQLite DB: queries · Reports aggregate data from local tables
- Settings → SQLite DB: store · Configuration is saved in the local database
- Audit log → SQLite DB: append · Important events are written to the audit log
- Receipts → SQLite DB: lookup · Receipt output reads completed sale data
- SQLite DB → Schema: defined by · SQLite structure is modeled by the Drizzle schema
- Migration → Schema: applies · Migration flow creates or upgrades schema state
- Migration → Init SQL: uses · Startup migration relies on the initial SQL artifact
- Seed script → Migration: bootstraps · Seed workflow initializes the local schema first
- Main process → IPC layer: starts · Main process wires IPC during app bootstrap
- Main process → SQLite DB: opens · Main process creates the local SQLite connection
- Start Electron → Main process: launches · Development helper starts the Electron runtime
- Vite config → POS UI: builds · Vite serves and bundles the React renderer
- Shared types → Preload bridge: contracts · Shared types keep bridge payloads aligned
- Shared types → POS UI: contracts · Renderer UI consumes the shared contract
- Shared types → IPC layer: contracts · IPC payloads and responses use shared types
- Sales → Receipts: emits · Completed sales feed receipt generation
- Sales → Audit log: records · Sales actions create audit events
- Settings → Audit log: records · Configuration changes are audited
