# sshopnil/biztar architecture

> Architecture diagram of the GitHub repository sshopnil/biztar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sshopnil/biztar
- Repository: https://github.com/sshopnil/biztar

## Overview

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: [`app/[domain]/(client)`](https://github.com/sshopnil/biztar/tree/main/app/[domain]/(client)) (Client Routes), [`app/[domain]/admin`](https://github.com/sshopnil/biztar/tree/main/app/[domain]/admin) (Admin Routes), [`lib`](https://github.com/sshopnil/biztar/tree/main/lib) (Shared Lib), [`prisma/schema.prisma`](https://github.com/sshopnil/biztar/blob/main/prisma/schema.prisma) (Tenant DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface_storefront["Storefront"]
  node_tenant_client_routes["Client Routes<br/>tenant storefront routes"]
  node_tenant_seo_routes["SEO Routes<br/>tenant metadata<br/>[robots.ts]"]
end

subgraph group_surface_admin["Tenant Admin"]
  node_tenant_admin_routes["Admin Routes"]
  node_tenant_admin_layout["Admin Shell<br/>[layout.tsx]"]
end

subgraph group_surface_platform["Platform Control"]
  node_tenant_platform_app["Platform App<br/>local control plane"]
  node_platform_login["Platform Login<br/>platform auth ui<br/>[page.tsx]"]
end

subgraph group_core_backend["Core Backend"]
  node_middleware{{"Middleware<br/>routing/security<br/>[middleware.ts]"}}
  node_ui_client["Client UI<br/>interactive storefront ui"]
  node_ui_admin["Admin UI<br/>operational ui"]
  node_ui_server["Server UI<br/>data-bound ui"]
  node_server_actions{{"Actions<br/>business logic"}}
  node_tenant_actions{{"Tenant Actions"}}
  node_api_routes{{"API Routes<br/>integration endpoints"}}
  node_auth_system{{"Auth<br/>[auth.ts]"}}
  node_media_delivery["Media<br/>asset delivery<br/>[route.ts]"]
  node_prisma_main[("Tenant DB<br/>prisma postgres<br/>[schema.prisma]")]
  node_prisma_platform[("Platform DB<br/>prisma postgres<br/>[schema.prisma]")]
  node_shared_lib["Shared Lib<br/>runtime helpers"]
  node_ops_tooling["Ops Tooling<br/>scripts and backups"]
end

node_middleware -->|"routes"| node_tenant_client_routes
node_middleware -->|"protects"| node_tenant_admin_routes
node_middleware -->|"separates"| node_tenant_platform_app
node_tenant_client_routes -->|"uses"| node_ui_client
node_tenant_client_routes -->|"uses"| node_ui_server
node_tenant_client_routes -->|"mutates via"| node_server_actions
node_tenant_client_routes -->|"uses"| node_tenant_actions
node_tenant_client_routes -->|"reads from"| node_api_routes
node_tenant_client_routes -->|"serves"| node_media_delivery
node_tenant_seo_routes -->|"uses"| node_shared_lib
node_tenant_admin_routes -->|"wraps"| node_tenant_admin_layout
node_tenant_admin_routes -->|"uses"| node_ui_admin
node_tenant_admin_routes -->|"mutates via"| node_server_actions
node_tenant_admin_routes -->|"integrates with"| node_api_routes
node_tenant_admin_routes -->|"persists to"| node_prisma_main
node_tenant_platform_app -->|"starts at"| node_platform_login
node_tenant_platform_app -->|"persists to"| node_prisma_platform
node_server_actions -->|"writes"| node_prisma_main
node_tenant_actions -->|"writes"| node_prisma_main
node_api_routes -->|"authenticates"| node_auth_system
node_api_routes -->|"uses"| node_shared_lib
node_media_delivery -->|"uses"| node_shared_lib
node_shared_lib -->|"connects"| node_prisma_main
node_shared_lib -->|"connects"| node_prisma_platform
node_ops_tooling -->|"operates on"| node_prisma_main
node_ops_tooling -->|"operates on"| node_prisma_platform
node_ops_tooling -->|"supports"| node_server_actions

click node_middleware "https://github.com/sshopnil/biztar/blob/main/middleware.ts"
click node_tenant_client_routes "https://github.com/sshopnil/biztar/tree/main/app/[domain]/(client)"
click node_tenant_seo_routes "https://github.com/sshopnil/biztar/blob/main/app/[domain]/robots.ts"
click node_tenant_admin_routes "https://github.com/sshopnil/biztar/tree/main/app/[domain]/admin"
click node_tenant_admin_layout "https://github.com/sshopnil/biztar/blob/main/app/[domain]/admin/layout.tsx"
click node_tenant_platform_app "https://github.com/sshopnil/biztar/tree/main/app/app"
click node_platform_login "https://github.com/sshopnil/biztar/blob/main/app/app/login/page.tsx"
click node_ui_client "https://github.com/sshopnil/biztar/tree/main/components/client"
click node_ui_admin "https://github.com/sshopnil/biztar/tree/main/components/admin"
click node_ui_server "https://github.com/sshopnil/biztar/tree/main/components/server"
click node_server_actions "https://github.com/sshopnil/biztar/tree/main/app/actions"
click node_tenant_actions "https://github.com/sshopnil/biztar/tree/main/app/[domain]/actions"
click node_api_routes "https://github.com/sshopnil/biztar/tree/main/app/api"
click node_auth_system "https://github.com/sshopnil/biztar/blob/main/auth.ts"
click node_media_delivery "https://github.com/sshopnil/biztar/blob/main/app/media/[...path]/route.ts"
click node_prisma_main "https://github.com/sshopnil/biztar/blob/main/prisma/schema.prisma"
click node_prisma_platform "https://github.com/sshopnil/biztar/blob/main/prisma/platform/schema.prisma"
click node_shared_lib "https://github.com/sshopnil/biztar/tree/main/lib"
click node_ops_tooling "https://github.com/sshopnil/biztar/tree/main/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tenant_client_routes,node_tenant_seo_routes toneBlue
class node_tenant_admin_routes,node_tenant_admin_layout toneAmber
class node_tenant_platform_app,node_platform_login toneMint
class node_middleware,node_ui_client,node_ui_admin,node_ui_server,node_server_actions,node_tenant_actions,node_api_routes,node_auth_system,node_media_delivery,node_prisma_main,node_prisma_platform,node_shared_lib,node_ops_tooling toneRose
```

## Components

### Storefront

Tenant public shopping experience routed by domain.

- [Client Routes](https://github.com/sshopnil/biztar/tree/main/app/[domain]/(client)): tenant storefront routes · Public tenant pages for home, menu, story, cart, buy, account, and receipt flows. · `app/[domain]/(client)`
- [SEO Routes](https://github.com/sshopnil/biztar/blob/main/app/[domain]/robots.ts): tenant metadata · Tenant robots and sitemap endpoints for discovery. · `app/[domain]/robots.ts`

### Tenant Admin

Per-tenant operations console for commerce and fulfillment.

- [Admin Routes](https://github.com/sshopnil/biztar/tree/main/app/[domain]/admin): tenant admin routes · Operational back office pages for orders, products, inventory, customers, analytics, billing, settings, and content. · `app/[domain]/admin`
- [Admin Shell](https://github.com/sshopnil/biztar/blob/main/app/[domain]/admin/layout.tsx): 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](https://github.com/sshopnil/biztar/tree/main/app/app): local control plane · Local-only platform administration surface for onboarding, plans, companies, and users. · `app/app`
- [Platform Login](https://github.com/sshopnil/biztar/blob/main/app/app/login/page.tsx): platform auth ui · Entry point for the local super-admin experience. · `app/app/login/page.tsx`

### Core Backend

Shared request, logic, persistence, and operational subsystems.

- [Middleware](https://github.com/sshopnil/biztar/blob/main/middleware.ts): routing/security · Entry-time routing and boundary enforcement for tenant and platform requests. · `middleware.ts`
- [Client UI](https://github.com/sshopnil/biztar/tree/main/components/client): interactive storefront ui · Interactive storefront components for cart, checkout, product, story, and home experiences. · `components/client`
- [Admin UI](https://github.com/sshopnil/biztar/tree/main/components/admin): operational ui · Tenant admin components for boards, forms, settings, exports, and moderation. · `components/admin`
- [Server UI](https://github.com/sshopnil/biztar/tree/main/components/server): data-bound ui · Server-rendered page fragments that assemble tenant data for the storefront. · `components/server`
- [Actions](https://github.com/sshopnil/biztar/tree/main/app/actions): business logic · Server action boundary for mutable tenant and platform operations. · `app/actions`
- [Tenant Actions](https://github.com/sshopnil/biztar/tree/main/app/[domain]/actions): tenant actions · Tenant-scoped actions for settings and other domain-specific mutations. · `app/[domain]/actions`
- [API Routes](https://github.com/sshopnil/biztar/tree/main/app/api): integration endpoints · Auth, health, tracking, CSP reporting, menu, home-sections, and admin logout endpoints. · `app/api`
- [Auth](https://github.com/sshopnil/biztar/blob/main/auth.ts): nextauth auth · Tenant and platform authentication configuration and route handlers. · `auth.ts`
- [Media](https://github.com/sshopnil/biztar/blob/main/app/media/[...path]/route.ts): asset delivery · Public media routes and Cloudinary/server-media helpers for image and content delivery. · `app/media/[...path]/route.ts`
- [Tenant DB](https://github.com/sshopnil/biztar/blob/main/prisma/schema.prisma): prisma postgres · Primary Prisma schema and migrations for tenant commerce and operations data. · `prisma/schema.prisma`
- [Platform DB](https://github.com/sshopnil/biztar/blob/main/prisma/platform/schema.prisma): prisma postgres · Separate Prisma schema for the platform control plane. · `prisma/platform/schema.prisma`
- [Shared Lib](https://github.com/sshopnil/biztar/tree/main/lib): runtime helpers · Logging, audit, caching, rate limiting, domain helpers, tracking, translations, and Prisma clients. · `lib`
- [Ops Tooling](https://github.com/sshopnil/biztar/tree/main/scripts): scripts and backups · Backups, restores, migrations, reset scripts, seed data, checks, and performance tooling. · `scripts`

## Connections

- 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.
