How sshopnil/biztar works
1. Top-level shape
- This is a Next.js App Router monorepo-style application that combines three major surfaces: a tenant storefront, a tenant admin console, and a local-only super-admin control plane.
- The repo is structured around route groups and server actions rather than a separate frontend/backend split.
2. Tenant storefront (app/[domain]/(client))
- The public customer experience lives under app/[domain]/(client), which suggests multi-tenant routing by domain.
- Pages include home, menu, story, cart, buy/product detail, account, orders receipt, and supporting SEO endpoints like robots.ts and sitemap.ts.
- This surface is optimized for customer-facing commerce flows: browsing, carting, checkout, account history, and order receipt viewing.
3. Tenant admin console (app/[domain]/admin)
- The admin area is a large operational back office for each tenant, with pages for orders, products, inventory, categories, promos, reviews, customers, analytics, billing, settings, security, theme, shop configuration, and landing content.
- Some admin pages have dedicated client components and action files, indicating a mix of server-rendered shells and interactive management panels.
- This is the primary operations layer for restaurant/kitchen and retail management.
4. Local platform control plane (app/app)
- app/app is a separate platform-level admin experience with login, plans, dashboard, tenant management, and company/user modals.
- The README says this is local-only and does not ship to production; it uses a separate platform database and is the control plane for tenant onboarding and platform administration.
5. Server actions as the business-logic boundary
- The repo uses many server action modules under app/actions plus tenant-scoped actions under app/[domain]/actions.
- These actions are the main application-service boundary for mutable operations such as orders, products, inventory, uploads, notifications, security, settings, analytics, coupons, promotions, reviews, tenant/domain management, and backups.
- In architecture terms, UI components call into these actions rather than directly into database logic.
6. API routes for cross-cutting concerns
- app/api hosts endpoints for auth, platform auth, health checks, track/event capture, CSP reporting, menu/home-section data, logout/clear-auth, and debug helpers.
- These routes are where non-UI integrations and operational hooks live: authentication callbacks, monitoring, telemetry, and policy reporting.
- The /api/health endpoint is explicitly part of the availability story in the README.
7. Data layer and persistence
- The primary persistence layer is Prisma + PostgreSQL, with schemas in prisma/schema.prisma and a separate prisma/platform/schema.prisma for the platform control plane.
- The repository includes many migrations, backup snapshots, reset/restore scripts, and schema drift checks, showing that database state management is a first-class operational concern.
- Backups contain domain entities like orders, products, inventory, security logs, sessions, trusted devices, site config, and tenant-related records.
8. Domain model and key subsystems
- The file tree reveals a fairly rich commerce domain: orders, order items, products, categories, coupons, promos, inventory, reviews, notifications, settings, security logs, trusted devices, sessions, hubs, delivery/payment config, hero/story content, and analytics/events.
- There is also a delivery/logistics flavor: inventory boards, fulfillment boards, hub selection, and print workflows for orders.
- This is not just storefront commerce; it is an omnichannel operations platform for live seafood delivery and restaurant-style fulfillment.
9. Authentication, authorization, and security
- Auth is implemented via NextAuth-style routes and config files (auth.ts, auth.config.ts, auth.platform.ts) with separate concerns for tenant and platform auth.
- Security features include trusted-device verification, rate limiting, CSP reporting, audit logging, and admin-only protections.
- middleware.ts likely enforces tenant/platform routing and security boundaries, which is important for diagramming request flow before a page or API route executes.
10. UI composition boundaries
- components/client, components/admin, components/server, and components/shared separate UI by execution context and concern.
- Client components cover interactive storefront behaviors like cart drawers, checkout, product modals, home/story experiences, and recommendation surfaces.
- Admin components focus on operational forms, boards, tabs, and settings panels; server components provide data-bound page scaffolding.
11. Media, assets, and content delivery
- Media is served through dedicated routes under app/media/[...path], and there are utilities for media and Cloudinary integration in lib/media.ts, lib/server-media.ts, and lib/cloudinary.ts.
- Public assets include images, story content, audio, and certification/media folders, indicating the storefront also has strong brand/storytelling content.
- This makes media delivery a distinct subsystem from core transactional data.
12. Shared infrastructure and runtime helpers
- lib/ contains the shared operational primitives: Prisma clients, logging, audit, rate limiting, deployment/domain helpers, caching/menu cache, translations, and tracking.
- The README references Prisma Accelerate / SWR-style edge caching, request memoization, and ISR for public pages, so performance optimization is part of the architecture rather than an afterthought.
- instrumentation.ts and instrumentation-client.ts show there is application-level observability bootstrapping.
13. Operational tooling and lifecycle management
- The repo includes substantial tooling for backups, restores, seed data, tenant migration, cleanup, password resets, DB checks, and performance index application.
- These scripts indicate the platform is designed to be operated, migrated, and audited in production-like environments, not just developed locally.
- Docs folders reinforce this with security runbooks, migration guides, onboarding docs, and certification checklists.
14. CI/CD and quality gates
- GitHub Actions, Husky pre-commit/pre-push hooks, lint/test tooling, Playwright E2E tests, and Vitest are all present.
- The test suite includes tenant isolation and checkout scenarios, which are architecturally important because they validate the multi-tenant boundary and commerce flow integrity.
- The CI/security workflows suggest the repo treats delivery and compliance as part of the system design.
15. How requests likely flow
- Typical storefront flow: browser request hits middleware/domain routing → storefront page renders → server components/actions fetch data via Prisma/cache → client components handle cart/checkout interactions → API routes handle auth, tracking, and health.
- Typical admin flow: authenticated admin request enters admin route group → trusted-device/auth checks apply → admin pages call server actions → actions mutate Prisma-backed domain tables and emit audit/log entries.
- Platform flow: local-only app surface manages tenants and plans against a separate platform database.
16. Architectural takeaway
- The repo is best diagrammed as a multi-tenant Next.js application with three tiers of user experience: customer storefront, tenant operations/admin, and local platform control plane.
- The key boundaries are route-group isolation, server-action business logic, Prisma/Postgres persistence, and security middleware/auth.
- Everything else—media, analytics, backups, and compliance tooling—supports those core flows.
Main entry points: (client) Client Routes · admin Admin Routes · lib Shared Lib · schema.prisma Tenant DB
Components 19
Storefront
Tenant public shopping experience routed by domain.
- Client Routes · Public tenant pages for home, menu, story, cart, buy, account, and receipt flows.
app/[domain]/(client) - SEO Routes · Tenant robots and sitemap endpoints for discovery.
app/[domain]/robots.ts
Tenant Admin
Per-tenant operations console for commerce and fulfillment.
- Admin Routes · Operational back office pages for orders, products, inventory, customers, analytics, billing, settings, and content.
app/[domain]/admin - Admin Shell · Shared tenant admin layout and dashboard scaffolding.
app/[domain]/admin/layout.tsx
Platform Control
Local-only super-admin plane for tenant and plan management.
- Platform App · Local-only platform administration surface for onboarding, plans, companies, and users.
app/app - Platform Login · Entry point for the local super-admin experience.
app/app/login/page.tsx
Core Backend
Shared request, logic, persistence, and operational subsystems.
- Middleware · Entry-time routing and boundary enforcement for tenant and platform requests.
middleware.ts - Client UI · Interactive storefront components for cart, checkout, product, story, and home experiences.
components/client - Admin UI · Tenant admin components for boards, forms, settings, exports, and moderation.
components/admin - Server UI · Server-rendered page fragments that assemble tenant data for the storefront.
components/server - Actions · Server action boundary for mutable tenant and platform operations.
app/actions - Tenant Actions · Tenant-scoped actions for settings and other domain-specific mutations.
app/[domain]/actions - API Routes · Auth, health, tracking, CSP reporting, menu, home-sections, and admin logout endpoints.
app/api - Auth · Tenant and platform authentication configuration and route handlers.
auth.ts - Media · Public media routes and Cloudinary/server-media helpers for image and content delivery.
app/media/[...path]/route.ts - Tenant DB · Primary Prisma schema and migrations for tenant commerce and operations data.
prisma/schema.prisma - Platform DB · Separate Prisma schema for the platform control plane.
prisma/platform/schema.prisma - Shared Lib · Logging, audit, caching, rate limiting, domain helpers, tracking, translations, and Prisma clients.
lib - Ops Tooling · Backups, restores, migrations, reset scripts, seed data, checks, and performance tooling.
scripts
Connections 27
- Middleware → Client Routes: routes · Directs tenant requests into the public storefront surface.
- Middleware → Admin Routes: protects · Applies routing and security boundaries before admin pages render.
- Middleware → Platform App: separates · Keeps the local platform plane distinct from tenant traffic.
- Client Routes → Client UI: uses · Storefront pages compose interactive client components.
- Client Routes → Server UI: uses · Storefront pages pull in server-rendered content sections.
- Client Routes → Actions: mutates via · Checkout, cart, account, and order flows invoke server actions.
- Client Routes → Tenant Actions: uses · Tenant-scoped settings and related mutations feed the storefront.
- Client Routes → API Routes: reads from · Public pages rely on menu, home-section, tracking, and auth APIs.
- Client Routes → Media: serves · Storefront pages consume media and brand assets.
- SEO Routes → Shared Lib: uses · SEO endpoints share formatting and deployment helpers.
- Admin Routes → Admin Shell: wraps · Admin pages are nested under a shared operational shell.
- Admin Routes → Admin UI: uses · Admin pages are built from operational components and boards.
- Admin Routes → Actions: mutates via · Orders, products, inventory, promos, reviews, analytics, and settings use server actions.
- Admin Routes → API Routes: integrates with · Admin flows use auth/logout and operational API endpoints.
- Admin Routes → Tenant DB: persists to · Admin operations read and write tenant commerce data.
- Platform App → Platform Login: starts at · Platform control plane begins with a separate login surface.
- Platform App → Platform DB: persists to · Platform administration uses its own database schema.
- Actions → Tenant DB: writes · Primary business mutations flow through Prisma-backed tenant tables.
- Tenant Actions → Tenant DB: writes · Tenant-scoped actions mutate the shared tenant datastore.
- API Routes → Auth: authenticates · Auth and platform-auth routes are handled through NextAuth-style config.
- API Routes → Shared Lib: uses · Telemetry, health, CSP, and debug endpoints rely on shared runtime helpers.
- Media → Shared Lib: uses · Media handling is backed by shared media and Cloudinary utilities.
- Shared Lib → Tenant DB: connects · Shared Prisma client and data helpers bridge application code to tenant persistence.
- Shared Lib → Platform DB: connects · Platform-specific Prisma access supports the local control plane.
- Ops Tooling → Tenant DB: operates on · Scripts manage backups, restores, migrations, resets, and checks for tenant data.
- Ops Tooling → Platform DB: operates on · Operational scripts also support the platform database lifecycle.
- Ops Tooling → Actions: supports · Maintenance scripts complement runtime mutations and domain workflows.