How uaibak/poscore works
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: ipc.ts IPC layer · db.ts SQLite DB · sales.ts Sales · audit.ts Audit log
Components 20
Desktop runtime
Electron main process, preload bridge, and local persistence
- Main process · Desktop runtime entrypoint and bootstrap
src/main/main.ts - IPC layer · Bridges renderer requests into main-process handlers
src/main/ipc.ts - Preload bridge · Safe API surface exposed to the renderer
src/preload/preload.ts - Auth · Credentials, access checks, and user identity
src/main/services/auth.ts - Security · Role permissions and sensitive workflow guards
src/main/services/security.ts - Catalog · Products, categories, and stock-facing records
src/main/services/catalog.ts - Sales · Orders, payments, returns, and inventory updates
src/main/services/sales.ts - Receipts · Receipt generation and printer-oriented formatting
src/main/services/receipt.ts - Reports · Sales and inventory reporting plus CSV/PDF export
src/main/services/reports.ts - Settings · Store, tax, printer, backup, and locale options
src/main/services/settings.ts - Audit log · Immutable operational event logging
src/main/services/audit.ts - SQLite DB · SQLite connection and transactional storage
src/main/database/db.ts - Schema · Table and relation definitions
src/main/database/schema.ts - Migration · First-launch schema creation and upgrade flow
src/main/database/migration.ts - Init SQL · Initial SQL migration file
src/main/database/001_initial.sql
Renderer UI
React cashier/admin interface
- POS UI · Cashier and admin desktop interface
src/renderer/main.tsx
Shared contract
Types shared across the Electron boundary
- Shared types · Common IPC and domain payload definitions
src/shared/types.ts
Tooling
Development and seed workflow
- Seed script · Creates schema and sample data for verification
scripts/seed.ts - Start Electron · Development startup helper for Electron
scripts/start-electron.ts - Vite config · Renderer development and build configuration
vite.config.ts
Connections 30
- 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