Database Engineering

Every domain is split by role: distributors and retailers get separate controllers, services, and notification tables over one shared schema of 24+ tables. Orders move through an explicit status-driven state machine, so an order can never skip a step or be acted on by the wrong side of the marketplace.

Authentication and application data have an explicit boundary: Supabase owns the session and JWT identity, while authenticated route handlers derive the user id server-side before services and repositories query Neon. That boundary also leaves a contained path for the planned Spring Boot API migration.

Every endpoint returns one uniform envelope — { payload, message, code, error } — so the frontend unwraps all responses identically. Auth tokens are persisted server-side, which makes logout an actual revocation instead of just deleting a client token. And the storefront falls back to mock data whenever the API is empty or unreachable, so the UI is demoable out of the box.

Dependencies flow one way — common-api → security-api → todoapi — so the auth service can never depend on a business API. The schema belongs to Flyway: Hibernate only validates it, which turns silent schema drift into a startup failure. Auth state that must be revocable (refresh tokens, blacklisted JWTs, reset/verification/unlock tokens) lives in dedicated tables rather than in stateless token claims.

The UI is deliberately insulated from backend ownership: screens call lib/api clients, which call /api/v1 paths. Some paths still reach Spring Boot while migrated domains run through Next.js route handlers, services, repositories, and Drizzle. Private owner fields stay server-side and never enter public property or Telegram payloads.