POS System Technical Analysis

Current: Zod is used for manual .parse(request.body) calls inside route handlers. Fastify's native JSON Schema validation is not used. Query params and path params are cast with as type assertions — completely unvalidated.

Best Practice: Fastify is optimized for JSON Schema validation via schema option. Use fastify-type-provider-zod for both Zod DX and Fastify's compiled validation.

Fix: Adopt fastify-type-provider-zod to register Zod schemas in Fastify's schema option. At minimum, validate query and path params.

Current: Global error handler detects ZodError by checking error.constructor.name === 'ZodError' (brittle, can break with minification). Some routes swallow errors and return 400 for all failures including 500-level DB errors. The /me endpoint returns errors without a proper HTTP status code.

Fix: Use instanceof ZodError. Differentiate client errors (400) from server errors (500) in catch blocks. Ensure all error paths set proper HTTP status codes.

Current: Global rate limiting disabled (global: false). Only /login and /pin-login have rate limits (5 req/min).

Missing: /change-credential, /refresh token endpoint, and sync push endpoint have no rate limiting. No global fallback.

Fix: Add rate limiting to sensitive endpoints. Add global rate limit as safety net (e.g., 1000 req/min).

Current: The authenticate decorator is added to the root instance without fastify-plugin wrapping. Works but could break if plugin load order changes.

Fix: Wrap shared decorators with fastify-plugin for explicit encapsulation breaking.

Current: 22 route modules imported explicitly in app.ts. No grouping by domain.

Fix: Consider @fastify/autoload or group routes by domain (HQ management, POS operations, sync) into parent plugins.

Current: Only unique indexes exist (from constraints). No non-unique indexes defined anywhere.

Critical missing indexes: sale_items.sale_id, sale_payments.sale_id, user_store_roles.user_id, sales.store_id, sales.created_at, sales.status, inventory_adjustments.product_id, products.department_id, products.sync_version, transfers.from_store_id, transfers.to_store_id, register_sessions.store_id, product_specials composite index.

Fix: Create a migration adding all missing indexes. Priority: FK columns used in joins, then filter columns, then sync_version columns.

Current: GET /api/v1/sales has a severe N+1 problem. For each sale, it queries items, then for each item it queries taxes, then queries payments. For a page of 50 sales with 5 items each: 50 (items) + 250 (taxes) + 50 (payments) = 350 queries per page load.

Fix: Collect all saleIds, then batch query: SELECT * FROM sale_items WHERE sale_id IN (...). Same for taxes and payments. Reduces 350 queries to 4.

Current: processEnvelope() does NOT use transactions for multi-step operations. The shouldRemoteWin check-then-update pattern has a Time-of-Check-to-Time-of-Use race condition without a transaction.

Fix: Wrap sync push envelope processing in transactions. The select-then-upsert pattern needs to be atomic.

Current: No relations() defined anywhere. All joins are manual SQL-style innerJoin/leftJoin. No relational query API available.

Fix: Define Drizzle relations for key relationships (sale -> saleItems, product -> department, etc.). Use db.query relational API for reads needing eager loading.

Current: Single postgres() connection with no pool configuration. No explicit pool size, no connection timeout, no idle timeout, no SSL for production.

Fix: Configure pool explicitly: postgres(url, { max: 20, idle_timeout: 30, connect_timeout: 10 }).

Current: Products route constructs WHERE with manual SQL concatenation instead of and(...conditions) like sales route does correctly.

Fix: Standardize on and(...conditions) pattern everywhere.

Current: Single JWT secret for all token types (access, refresh, store_sync). Access tokens don't include type: 'access'. The /me endpoint doesn't verify the token type. A refresh or sync token could be used as an access token.

Fix: Add type: 'access' to access tokens. Verify type in the authenticate decorator. Use separate secrets or iss/aud claims for different token types.

Current: Refresh token is a signed JWT with 7-day expiry. No server-side storage, no rotation, no family tracking. When a user is deactivated, their refresh tokens remain valid until natural expiry.

Fix: Store refresh tokens in DB. On refresh, invalidate old token and issue new one (rotation). Check user isActive on refresh.

Current: PIN login iterates ALL active users and calls bcrypt.compare() against each until a match. With 100 users, worst case is ~10 second login (100 x ~100ms). Failed PINs always iterate all users; successful PINs stop early — timing attack vector. PIN uniqueness not enforced.

Fix: Enforce PIN uniqueness. Store a PIN hint or short hash for pre-filtering. Add constant-time comparison.

Current: requirePermission() loads all permissions from DB on every request (2-3 queries: userStoreRoles + rolePermissions JOIN permissions). Duplicated logic between auth-guard.ts and auth/routes.ts. No caching.

Fix: Consolidate permission loading. Cache permissions per userId with short TTL (60s) or include permissions in JWT.

Current: WebSocket auth passes sync_token as a URL query parameter. Tokens in query strings are logged by reverse proxies and can leak via Referer headers.

Fix: Use the existing message-based auth flow as the primary mechanism. Remove query-string token support.

Current: 40s pong timeout with 30s ping interval gives only 10s grace period. Network jitter could cause false disconnects. Dual heartbeat mechanism (protocol-level ping from server, app-level heartbeat from store) is redundant.

Fix: Increase pong timeout to 60s or reduce ping interval to 15s.

Current: All connected stores held in a single in-memory Map. Broadcast iterates all entries. No multi-process support.

Fix: Acceptable for current scale (<50 stores). For larger scale, introduce Redis pub/sub for cross-process routing.

HQ Server: 373 tests | Store Server: 185 tests

Framework: Vitest 3.x with global test setup, PostgreSQL test databases. Integration tests against real DB (no mocks). Global setup drops/recreates database, runs migrations, seeds data.

Current: Tests within the same file share state (e.g., createdProductId set in POST test, used in PUT test). No per-test cleanup. Tests depend on execution order.

Fix: Use beforeEach for per-test data setup. Wrap tests in rolled-back transactions or don't depend on execution order.

Current: Tests cover happy paths, 404s, and permission enforcement. Missing: concurrent operations, sync push conflict resolution, JWT type confusion, PIN-login timing with multiple users.

Fix: Add tests for JWT type validation, sync conflict resolution, concurrent sale creation.

Current: sync-processor queue defined but has no worker. Queue names are string literals. console.error used instead of Fastify logger.

Fix: Implement the sync-processor worker or remove dead code. Use app logger.

Current: PosTerminalView.vue is 1400+ lines, ProductsView.vue is 900 lines, StoresView.vue is 586 lines. These combine data fetching, form handling, dialog management, and rendering in a single file.

Fix: Extract composables for data operations and split dialogs into child components. Target: no view exceeds ~300 lines of script.

Current: The tax breakdown calculation in completeSale() (checkout store) is duplicated nearly verbatim in preValidateSale() (CheckoutView).

Fix: Extract the tax breakdown builder into a shared function in @pos/tax-engine.

Current: formatMoney(cents) is defined locally in ProductsView, CheckoutView, StoresView, StoreInventoryView independently.

Fix: Extract useFormatMoney() composable or utility in @pos/ui-kit.

Update (Mar 2026): The @pos/pos-logic package extraction consolidates shared stores and composables. Utility extraction is the next step.

Current: Nearly every store has the same pattern: const payload = result.data as unknown as { data: T[] } | T[]; products.value = Array.isArray(payload) ? payload : ('data' in payload ? payload.data : []). This is repeated across all stores.

Fix: Handle response normalization once in the backend adapter's execute() method so stores never need to unwrap.

Update (Mar 2026): Partially addressed — 12 Pinia stores extracted to @pos/pos-logic and shared across all 4 apps, eliminating per-app store duplication.

Current: useCheckoutStore calls useCartStore(), useAuthStore(), useRegisterStore() at the top level of the store definition. Pinia docs warn this can cause circular dependency issues.

Fix: Move store cross-references inside actions: const cartStore = useCartStore() inside completeSale().

Current: useReportsStore has 11 nearly identical async functions sharing one loading/error ref. Loading Report A clobbers Report B's loading state.

Fix: Split into per-report composables or add per-report loading state.

Current: applySpecialsToProducts() mutates product.specialPrice directly on items inside products.value, circumventing Vue's reactivity tracking for nested properties.

Fix: Create new objects instead of mutating existing refs in place.

Current: Auth store manually implements localStorage persistence. Works but non-standard.

Fix: Consider pinia-plugin-persistedstate which handles edge cases (storage quota, serialization errors).

Current: No form validation library (Vee-Validate, FormKit, or manual validation). Users can submit empty product names, zero-price items, etc. PrimeVue 4's built-in invalid prop is not used.

Fix: Adopt Vee-Validate + Zod or at minimum use PrimeVue's :invalid prop with manual validation.

Current: CheckoutView.vue still imports Dropdown (deprecated in PrimeVue 4). Other views correctly use Select.

Fix: Replace all Dropdown imports with Select.

Current: All feedback is via inline Message components. Ephemeral success/error notifications should use PrimeVue's Toast service for better UX.

Fix: Add PrimeVue ToastService and use useToast() for success/error notifications.

Current: Multiple views use inline style="font-size:0.8125rem;...". Should use CSS classes for consistency and dark-mode safety.

Fix: Replace inline styles with scoped CSS classes.

Current: PrimeVue 4 introduced Tabs/TabList/Tab/TabPanels API. The older TabView/TabPanel API is still used in ProductsView.

Current: The beforeEach guard waits for authStore.initializing with a manual $subscribe + Promise pattern. Fragile.

Fix: Replace with authStore.whenReady() that returns a cached promise.

Current: No onError handler on the router. If a lazy-loaded chunk fails to load (network error), the user sees nothing.

Fix: Add router.onError() with a retry/reload mechanism.

Current: createRouter does not set scrollBehavior. Scroll position not reset on navigation.

Fix: Add scrollBehavior: () => ({ top: 0 }) to router config.

Current: ProductsView.vue defines its own Product, Department, TaxGroup, Supplier, Store interfaces nearly identical to @pos/shared-types. Same in CheckoutView, StoreInventoryView, etc. Every view re-defines types that already exist.

Fix: Import from @pos/shared-types instead of re-defining interfaces in views.

Current: Multiple stores use result.data as unknown as { data: T[] } | T[] to handle inconsistent API response shapes. Bypasses type safety entirely. Root cause: backend adapter's response unwrapping is incomplete.

Fix: Fix the backend adapter to consistently unwrap responses, eliminating all as unknown as casts.

Current: StoresView.vue line 125 uses .map((s: any) => ({...})). Violates the project's "no any" rule.

Fix: Replace with proper typed parameter.

Current: CheckoutView uses mobile-first (min-width breakpoints), while ProductsView and StoreInventoryView use desktop-first (max-width).

Fix: Standardize on mobile-first (recommended for POS targeting tablets).

Current: StoresView uses #10b981, #ef4444 directly instead of PrimeVue tokens. Will not adapt to dark mode correctly.

Fix: Use var(--p-green-500), var(--p-red-500) PrimeVue CSS variables.

Current: Multiple views contain hardcoded English text in violation of the project's "All user-facing text via vue-i18n" rule. Affected: StoresView ("Stores Dashboard", "Add Store", "Connected", etc.), StoreInventoryView ("Inventory", "Search products...", "Low Stock Only", etc.), LoginView ("PIN / Password"), and others.

Fix: Audit all views for hardcoded strings. Add keys to both en.json and es.json.

Current: Translation keys are plain strings. Typos in t('products.tilte') silently fail at runtime, showing the key instead of translated text.

Fix: Generate TypeScript types from en.json keys for type-safe t() calls.

Current: commandToEndpoint has 100+ entries mapping command strings to URLs. commandToMethod has 30+ if-chains. commandToSuffix has 30+ entries. No compile-time validation; typos silently fall through.

Fix: Replace with a typed registry object: { get_products: { method: 'GET', path: '/api/v1/products', paginated: true } }.

Current: The web adapter partially unwraps { success, data } responses but doesn't handle paginated responses consistently. Every store must re-unwrap with as unknown as casts.

Fix: Have the adapter fully normalize responses so stores receive clean typed data.

Current: No way to add global error handling (401 -> logout), request logging, or retry logic.

Fix: Add an interceptor chain for global 401 redirect and retry.

Current: Workbox config caches /api/ responses for 5 minutes. For a POS system handling financial transactions, stale API cache can lead to incorrect stock levels, prices, or duplicate sales.

Fix: Remove or restrict Workbox API caching to safe read-only endpoints only.

Current: PrimeVue is a large library. Without manualChunks, the entire PrimeVue code may end up in one vendor chunk.

Fix: Add manualChunks to split PrimeVue, Chart.js, and vue-i18n into separate vendor chunks.

Current: In turbo.json, "test": { "dependsOn": ["build"] } means every test run requires a full build, slowing feedback.

Fix: Change to "dependsOn": ["^build"] so tests only require dependency packages to be built.

Web Client: 248 tests | Packages: 211 tests

Framework: Vitest 3.x + @vue/test-utils + happy-dom

Current: The root package.json has a lint script but no ESLint configuration exists. No @typescript-eslint or eslint-plugin-vue.

Fix: Add ESLint with @typescript-eslint and eslint-plugin-vue.

Current: 20 stores x 21 entity types = 420 HTTP requests per 30 seconds = 14 req/sec to HQ. Most return 0 entities but each still runs a DB query. 420 PostgreSQL queries/30s for pull alone.

With batch pull (recommended): 20 requests per 30 seconds = 0.67 req/sec. Each runs ~21 queries but in a single round-trip.

Initial sync (10K products): ~10K rows x ~500 bytes = 5MB. Should be paginated.

Incremental (steady state): ~10-50 changed entities per cycle, <50KB. Negligible.

Push (100 sale_items): ~100 x 300 bytes = 30KB per batch. Negligible.

Current: postgres(config.databaseUrl) with default pool (10 connections). No explicit pool size, no monitoring. HQ handles 20 store sync connections + HQ manager clients + API calls. Could exceed default pool.

Fix: Configure explicit pool size: postgres(url, { max: 20 }). Add PgBouncer in transaction mode for HQ. Monitor pool utilization.

Current architecture: 2100 pull HTTP requests per 30 seconds = 70 req/sec. This stresses a single Node.js process. Would need:

• Batch pull endpoint (reduces to 100 req/30s = 3.3 req/sec)
• Read replicas for pull queries
• Load balancer if single HQ server is insufficient
• WebSocket moved to dedicated process using Redis pub/sub

Current: PostgreSQL and Redis have health checks. Application containers (hq-server, store-server) have NO health checks. Docker cannot detect if Node.js is unhealthy (event loop blocked, DB connection lost).

Fix: Add health check: test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]

Current: No connection retry on startup. No circuit breaker for DB operations. Pull requests from stores return 500 on HQ DB failure, triggering immediate retry with no backoff.

Fix: Add DB connection retry on startup (exponential backoff). Add circuit breaker for sync endpoints. Store should back off when HQ returns 5xx.

Current: deploy.sh runs docker compose up -d --force-recreate with 5-10 seconds downtime per deploy.

Fix: Acceptable for off-hours deploys. For 24/7, use Traefik health-check-based routing or blue-green.