Architecture & Design Overview

MEGSTAT POS is architected as a high-throughput, multi-tenant POS and enterprise ERP system designed around modern TypeScript tooling, edge-ready HTTP runtimes, and strict relational data models.

Architectural Principles

1. Lightweight Edge-Ready Runtime: Built on Hono, a fast, web-standard HTTP framework rather than heavyweight legacy frameworks.
2. Zero-Drift End-to-End Type Safety: A single change in database models ripples through @megstat/contracts and @megstat/schemas, surfacing as compile-time errors in frontend or backend code before runtime.
3. Single Choke Point Mutations: Risky operations—such as inventory depletion or cash balance updates—are constrained to dedicated service functions with guarded SQL semantics.
4. Single-File Deployment: The production server packages the entire API, database connectivity, and compiled React SPA assets into one minified script executed by Node.js.

Monorepo Topology

The repository is structured into workspace packages managed by npm:

┌─────────────────────────────────────────────────────────────┐
│                         megstat-pos                         │
├─────────────────┬─────────────────────────┬─────────────────┤
│  Applications   │   Core Packages         │   Tooling       │
├─────────────────┼─────────────────────────┼─────────────────┤
│ • backend/      │ • packages/db/          │ • scripts/      │
│   (Hono API)    │   (Prisma 7 & Client)   │   (esbuild)     │
│                 │                         │                 │
│ • frontend/     │ • packages/contracts/   │ • docs/         │
│   (React 19)    │   (Wire types & Selects)│   (VitePress)   │
│                 │                         │                 │
│                 │ • packages/schemas/     │                 │
│                 │   (Zod request schemas) │                 │
└─────────────────┴─────────────────────────┴─────────────────┘

Dependency Flow

To eliminate circular references and enforce strict layering, dependencies flow in one direction:

packages/db  (Prisma Schema, Client, Neon Adapter)
     │
     ▼
packages/contracts  (Select Constants, Wire Types, Response Envelope)
     │
     ▼
packages/schemas  (Zod Schemas validating Wire Types)
     │
     ├──────────────────────────┐
     ▼                          ▼
  backend                    frontend
 (Hono API)                (React 19 SPA)

Backend Layering (Layered Architecture)

The backend follows a strict 4-tier separation of concerns:

HTTP Request
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Middleware Layer (backend/src/middleware/)               │
│    • Tenant session resolution (session-driven, not query)  │
│    • JWT authentication & manager override verification     │
│    • RBAC permissions enforcement                           │
│    • Rate limiting & idempotency checking                   │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Routes Layer (backend/src/routes/)                       │
│    • Thin HTTP handlers (30+ domain route modules)          │
│    • Payload validation via validateWithSchema(schema)      │
│    • Delegates business logic to services                   │
│    • Formats responses through standard builders (ok, etc.) │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Services Layer (backend/src/services/)                   │
│    • applyMovement: Only path that mutates stock counts     │
│    • createSale: Atomic sale, inventory, and payment engine │
│    • numbering: Atomic sequential document code generation  │
│    • Cash register and drawer balance calculation           │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Data Layer (packages/db + packages/contracts)            │
│    • Prisma Client with Neon WebSocket driver               │
│    • Reusable Select constants (satisfies <Model>Select)    │
│    • Recursive toWire serialization for Decimals and Dates  │
└─────────────────────────────────────────────────────────────┘

Frontend Architecture

The frontend is a single-page application built on:

• React 19: Modern concurrent features and functional components.
• Vite: Rapid development server with esbuild pre-bundling.
• Tailwind CSS: Utility-first responsive design tailored for touchscreens and desktop POS monitors.
• Zustand: Fast, boilerplate-free state management across:
  • posStore: Cart items, custom lines, tax deductions, discounts, held tickets.
  • registerStore: Active drawer state, current cashier shift, cash totals.
  • authStore: User identity, token storage, tenant permissions.
  • tenantStore: Active tenant metadata, currency symbol, branch configuration.
• TanStack Query (React Query): Caching and asynchronous data synchronization for catalog, customer lookups, and reports.