# ealanisln/ready-set architecture

> Architecture diagram of the GitHub repository ealanisln/ready-set, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ealanisln/ready-set
- Repository: https://github.com/ealanisln/ready-set

## Overview

##### Project type and purpose
- This is a full-stack, multi-tenant delivery service web platform built on Next.js.
- It provides both a public “site” for clients, drivers, vendors, and a protected “admin” console; it handles user registration, authentication, dynamic deliveries (same-day, on-demand, catering), file uploads, blog/CMS, payments, and notifications.

##### File structure
- **src/app/**
- `(site)` subtree: all publicly available pages (marketing, auth UI, client/driver/vendor dashboards, order-status, payment, blog).
- `(backend)` subtree: the Next.js-rendered admin UI under `/admin`.
- `/api/*`: Next.js API route handlers for auth, user management, orders, dispatch, file uploads/downloads, form-submissions, subscriptions, etc.
- **prisma/**: ORM schema and migrations for PostgreSQL.
- **sanity/**: Headless CMS setup for blog/posts.
- **lib/** and **utils/**: business logic (email, uploads, error handling, notifications).
- **scripts/**: DB backup & sync tasks.
- **stripe/**: pricing data for payments.
- **Dockerfile**, **docker-compose.yml**: containerization for local/dev environment.

##### README for additional insights
- Confirms tech stack:
- Frontend & API: Next.js
- Database: PostgreSQL + Prisma
- UI library: Shadcn components
- Highlights features: multi-role user management, varied delivery options, email notifications, blog, payments.

a. Main components
- Client Web App (Next.js React UI for public site)
- Admin Web App (Next.js React UI for staff under `/admin`)
- Next.js Server (SSR/SSG + API routes)
- PostgreSQL Database via Prisma ORM
- Sanity Headless CMS
- File Storage subsystem (UploadThing or S3 abstraction)
- Email Service (SMTP or external provider)
- Payment Gateway (Stripe)
- Background/cron scripts for DB backup & sync
- External analytics (Google Analytics, MetriCool)
b. Relationships & interactions
- Browsers ⇄ Next.js Frontend
- Frontend UI → Next.js API routes → Prisma → PostgreSQL
- Next.js API routes → Sanity SDK for blog content → Sanity datastore
- Next.js API routes → UploadThing library → file storage
- Next.js API routes → Email service (via lib/email-service)
- Next.js API routes → Stripe (payment intents, webhooks)
- Cron scripts ↔ PostgreSQL for backups/sync
c. Architectural patterns & principles
- Monolithic Next.js app separating site vs. admin via filesystem routing (App Router).
- Layered architecture: UI → API layer → data access (Prisma) → persistence.
- Headless CMS decoupling blog content.
- Infrastructure as code (Docker + Docker Compose).
- Strong type safety (TypeScript throughout).
d. Key technologies/frameworks
- Next.js App Router
- Prisma ORM & migrations
- PostgreSQL
- Sanity (headless CMS)
- UploadThing (file uploads)
- Stripe (payments)
- Shadcn/UI (component library)

##### Detail
- Every “api/*” group (auth, orders, files, dispatch, form submissions).
- Sanity client under `/sanity/lib` as part of the CMS integration.
- Scripts container communicating to the same PostgreSQL instance for backups.
- Distinguish between public site traffic and protected admin traffic in the UI layer.
- Where middleware/authMiddleware applies to the API layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "User Browsers" 
        direction TB
        Browser["Web Browser"]:::frontend
    end

    %% UI Layer
    subgraph "Next.js Frontend (React)" 
        direction TB
        PublicSite["Public Site UI"]:::frontend
        AdminWebApp["Admin Console UI"]:::frontend
    end

    %% API Layer
    subgraph "Next.js API (Route Handlers)" 
        direction TB
        AuthMW["Auth Middleware"]:::backend
        NextAPI["API Route Handlers"]:::backend
    end

    %% Data Access Layer
    subgraph "Prisma ORM & Migrations" 
        direction TB
        PrismaSchema["Prisma Schema"]:::datastore
        PrismaMigrations["Prisma Migrations"]:::datastore
    end

    %% Datastore
    Postgres["PostgreSQL Database"]:::datastore

    %% CMS Integration
    subgraph "Sanity Headless CMS" 
        direction TB
        SanityConfig["sanity.config.ts"]:::external
        SanityCLI["sanity.cli.ts"]:::external
        SanityClient["Sanity Client & Queries"]:::external
        SanitySchema["Sanity Schema Types"]:::external
    end

    %% File Storage
    subgraph "File Storage Subsystem" 
        direction TB
        UploadAPI["/api/uploadthing"]:::backend
        UploadLogic["UploadThing Logic"]:::backend
        S3["S3 / UploadThing Cloud"]:::external
    end

    %% Email Service
    subgraph "Email Service" 
        direction TB
        EmailLogic["Email Service Logic"]:::external
        EmailTemplates["Email Templates"]:::external
        EmailAction1["actions/email.ts"]:::external
        EmailAction2["actions/send-download-email.ts"]:::external
    end

    %% Payments
    subgraph "Stripe Payment Gateway" 
        direction TB
        PricingData["pricingData.ts"]:::external
        PaymentPages["Payment Pages"]:::frontend
        SubscribeAPI["/api/subscribe"]:::backend
    end

    %% Utilities
    subgraph "Utility & Business Logic" 
        direction TB
        Utils["utils.ts"]:::backend
        Notifications["notifications.ts"]:::backend
        FormSubs["form-submissions.ts"]:::backend
    end

    %% Middleware
    Middleware["authMiddleware.ts"]:::backend

    %% Analytics
    subgraph "External Analytics" 
        direction TB
        GA["GoogleAnalytics.tsx"]:::external
        Metri["MetriCool.tsx"]:::external
    end

    %% Background Scripts
    subgraph "Background/Cron Scripts" 
        direction TB
        Backup["backup-db.ts"]:::scripts
        DBSync["db-sync.ts"]:::scripts
        Restore["restore-db.ts"]:::scripts
        FullSync["db-full-sync.ts"]:::scripts
    end

    %% Static Assets
    StaticAssets["public Assets (fonts/images/pdf)"]:::frontend

    %% Connections
    Browser -->|visits| PublicSite
    Browser -->|visits| AdminWebApp
    PublicSite -->|renders via| NextAPI
    AdminWebApp -->|renders via| NextAPI

    NextAPI -->|uses| AuthMW
    AuthMW -->|enforces| NextAPI

    NextAPI -->|reads/writes| PrismaSchema
    NextAPI -->|runs migrations| PrismaMigrations
    PrismaSchema -->|queries| Postgres
    PrismaMigrations -->|updates| Postgres

    NextAPI -->|fetches blog| SanityClient
    SanityClient -->|reads/writes| SanityConfig
    SanityClient -->|queries| SanitySchema

    NextAPI -->|handles uploads| UploadAPI
    UploadAPI -->|calls| UploadLogic
    UploadLogic -->|stores files| S3

    NextAPI -->|sends emails| EmailLogic
    EmailLogic -->|uses templates| EmailTemplates
    NextAPI -->|triggers| EmailAction1
    NextAPI -->|triggers| EmailAction2

    NextAPI -->|creates payment| PricingData
    NextAPI -->|handles subscription| SubscribeAPI
    PublicSite -->|displays| PaymentPages

    NextAPI -->|calls| Utils
    NextAPI -->|calls| Notifications
    NextAPI -->|calls| FormSubs

    Backup -->|backups to| Postgres
    DBSync -->|syncs| Postgres
    Restore -->|restores| Postgres
    FullSync -->|full sync| Postgres

    Browser -->|collects data| GA
    Browser -->|collects data| Metri

    PublicSite -->|serves| StaticAssets

    %% Click Events
    click PublicSite "https://github.com/ealanisln/ready-set/tree/stable-version/src/app/(site)"
    click AdminWebApp "https://github.com/ealanisln/ready-set/tree/stable-version/src/app/(backend)/admin"
    click NextAPI "https://github.com/ealanisln/ready-set/tree/stable-version/src/app/api"
    click PrismaSchema "https://github.com/ealanisln/ready-set/blob/stable-version/prisma/schema.prisma"
    click PrismaMigrations "https://github.com/ealanisln/ready-set/tree/stable-version/prisma/migrations"
    click Postgres "https://github.com/ealanisln/ready-set/tree/stable-version/prisma/"
    click SanityConfig "https://github.com/ealanisln/ready-set/blob/stable-version/sanity.config.ts"
    click SanityCLI "https://github.com/ealanisln/ready-set/blob/stable-version/sanity.cli.ts"
    click SanityClient "https://github.com/ealanisln/ready-set/blob/stable-version/src/sanity/lib/client.ts"
    click SanitySchema "https://github.com/ealanisln/ready-set/tree/stable-version/src/sanity/schemaTypes"
    click UploadAPI "https://github.com/ealanisln/ready-set/tree/stable-version/src/app/api/uploadthing"
    click UploadLogic "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/uploadthing.ts"
    click EmailLogic "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/email-service.ts"
    click EmailTemplates "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/email-templates.ts"
    click EmailAction1 "https://github.com/ealanisln/ready-set/blob/stable-version/src/app/actions/email.ts"
    click EmailAction2 "https://github.com/ealanisln/ready-set/blob/stable-version/src/app/actions/send-download-email.ts"
    click PricingData "https://github.com/ealanisln/ready-set/blob/stable-version/src/stripe/pricingData.ts"
    click PaymentPages "https://github.com/ealanisln/ready-set/tree/stable-version/src/app/(site)/(payment)"
    click SubscribeAPI "https://github.com/ealanisln/ready-set/blob/stable-version/src/app/api/subscribe/route.ts"
    click Utils "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/utils.ts"
    click Notifications "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/notifications.ts"
    click FormSubs "https://github.com/ealanisln/ready-set/blob/stable-version/src/lib/form-submissions.ts"
    click Middleware "https://github.com/ealanisln/ready-set/blob/stable-version/src/middleware/authMiddleware.ts"
    click GA "https://github.com/ealanisln/ready-set/blob/stable-version/src/components/Analytics/GoogleAnalytics.tsx"
    click Metri "https://github.com/ealanisln/ready-set/blob/stable-version/src/components/Analytics/MetriCool.tsx"
    click Backup "https://github.com/ealanisln/ready-set/blob/stable-version/src/scripts/backup-db.ts"
    click DBSync "https://github.com/ealanisln/ready-set/blob/stable-version/src/scripts/db-sync.ts"
    click Restore "https://github.com/ealanisln/ready-set/blob/stable-version/src/scripts/restore-db.ts"
    click FullSync "https://github.com/ealanisln/ready-set/blob/stable-version/src/scripts/db-full-sync.ts"
    click StaticAssets "https://github.com/ealanisln/ready-set/tree/stable-version/public"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000
    classDef backend fill:#d4edda,stroke:#28a745,color:#000
    classDef datastore fill:#fff3cd,stroke:#ffc107,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef scripts fill:#f8d7da,stroke:#dc3545,color:#000
```
