# snapscoutza/codex-snapscout-build architecture

> Architecture diagram of the GitHub repository snapscoutza/codex-snapscout-build, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snapscoutza/codex-snapscout-build
- Repository: https://github.com/snapscoutza/codex-snapscout-build

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** repository deployed on **Vercel**, with a mostly single-codebase architecture: UI pages, server-side route handlers, and shared domain libraries all live together.
   - The README shows it is synced from **v0.dev**, so the repo is driven as a product/UI workspace rather than a split frontend/backend system.

2. **Primary application surfaces**
   - The `app/` tree is organized into large product areas: **auth**, **dashboard**, **onboarding**, **profile**, **crew / crew-pools**, **marketplace**, **messaging**, **admin**, and several public marketing pages.
   - This suggests one app serving multiple personas: creators/crew, clients, admins, and unauthenticated visitors.

3. **Routing and page composition**
   - Pages are implemented as route segments under `app/`, with nested layouts for areas like `app/(dashboard)`, `app/(demo)`, and `app/onboarding`.
   - The public-facing site includes marketing and discovery pages, while authenticated experiences are grouped into dashboard-like sections and operational workflows.

4. **Backend API layer**
   - All backend functionality is exposed through `app/api/**/route.ts` handlers, so the server side is built as **serverless endpoints inside the Next.js app** rather than a separate service.
   - Major API groups include:
     - **Auth**: signup, callback, register user, password reset, email sending
     - **Crew pools / availability / call sheets**
     - **Portfolio / profile**
     - **Favorites**
     - **Marketplace / jobs**
     - **Payments / subscriptions**
     - **Webhooks**

5. **Identity and session boundary**
   - Authentication is handled through a **Supabase-based auth stack**, with custom helpers in `lib/auth.ts`, `lib/auth-helpers.ts`, `lib/supabase/*`, and `middleware.ts`.
   - `contexts/auth-context.tsx` provides client-side auth state, while `lib/supabase/server.ts`, `client.ts`, and `admin.ts` separate browser, server, and privileged operations.
   - This creates a clear boundary between authenticated UI, server-validated requests, and admin-level database access.

6. **Data persistence and schema management**
   - The project uses **Prisma** (`prisma/schema.prisma`, `lib/prisma.ts`) alongside Supabase utilities and generated `types/database*.ts`.
   - The presence of many SQL scripts under `scripts/` indicates active schema evolution and repair work, including crew pools, messaging, portfolio items, availability, and payment tables.
   - In architecture terms, the app appears to rely on a relational database with multiple feature-specific tables, managed through both Prisma and raw SQL migrations/scripts.

7. **Payments and subscription flow**
   - Payment processing is centered on **Paystack**, with route handlers for initialization, verification, subscription, and webhook processing.
   - Supporting logic lives in `lib/paystack.ts`, `lib/paystack-webhook.ts`, and `lib/db/subscriptions.ts`, showing a payment-to-database reconciliation flow.
   - The likely boundary is: UI initiates payment → API creates/verifies transaction → webhook confirms state → subscription records are updated.

8. **Email and notification subsystem**
   - Email is handled with **Resend**, via `lib/resend/*` and auth endpoints like `app/api/auth/send-email`.
   - The `components/email/*` and admin email pages indicate both operational email sending and an in-app email template/trigger management experience.
   - This is a separate concern from the core UI and data model, but it plugs into auth, onboarding, and possibly notifications.

9. **Crew operations subsystem**
   - Crew workflows are a major domain: `app/(dashboard)/crew-pools`, `availability`, `call-sheets`, and their corresponding API routes show a structured workflow around crew membership and scheduling.
   - Shared logic in `lib/crew-pools/api.ts` and `lib/availability.ts` supports pool membership, availability requests/responses, and call sheet distribution.
   - The data flow is likely: manage crew pool → collect availability → build call sheet → send/share with crew.

10. **Marketplace and discovery subsystem**
   - Marketplace pages cover available jobs, posted jobs, projects, applications, saved freelancers, and job detail views.
   - Supporting components in `components/marketplace/*`, plus utilities like `utils/application-status.ts`, suggest a workflow for posting, applying, tracking, and saving candidates/projects.
   - Discovery-related pages and components (`discover`, `creators`, `search`, `saved-profiles`) form a related talent discovery layer.

11. **Profile and onboarding pipeline**
   - Onboarding is highly segmented, with many step components in `components/onboarding/*` and configuration in `lib/onboarding-config.ts`.
   - Profile management is supported by `app/profile/*`, `app/onboarding/*`, `components/profile/*`, `components/portfolio/*`, and helpers such as `lib/profile-utils.ts` and `lib/profile-validation.ts`.
   - The architecture implies a staged setup flow: collect account type and role → gather profile/portfolio/business details → save to backend → unlock dashboard features.

12. **Admin and diagnostics**
   - Admin pages for analytics, schema debugging, schema management, and email-system support operational oversight.
   - Components like `components/admin/analytics-dashboard.tsx`, `components/admin/database-schema-manager.tsx`, and `components/database/schema-debugger.tsx` indicate internal tooling for monitoring and repairing the underlying data model.
   - This is an explicit maintenance boundary separate from normal user workflows.

13. **Shared UI and feature components**
   - The `components/` directory is heavily domain-organized, with reusable building blocks in `components/ui/` and feature-specific modules for auth, dashboard, crew, messaging, subscription, payment, and mobile preview.
   - This means the UI architecture is component-composed rather than page-isolated, with cross-cutting primitives like buttons, dialogs, toasts, menus, and cards used across domains.

14. **Supporting data, mocks, and utilities**
   - `lib/mock-data/*`, `data.tsx`, and many utility files provide seed/example content and presentation logic for demos or fallback rendering.
   - `docs/` and the `scripts/` folder show that the repo also carries operational knowledge: auth setup, email setup, SQL repair scripts, and database alignment tasks.

15. **Deployment/runtime implications**
   - Because everything is in a Next.js app and deployed on Vercel, the architecture is optimized for **serverless route handlers + React server/client components** rather than a separate always-on backend.
   - External services that materially affect the system are **Supabase** for auth/database access, **Paystack** for billing, **Resend** for email, **Prisma** for schema/data access, and **Vercel** for hosting and deployment.

Main entry points: [`app/layout.tsx`](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/layout.tsx) (Next.js app), [`components/dashboard/main-dashboard.tsx`](https://github.com/snapscoutza/codex-snapscout-build/blob/main/components/dashboard/main-dashboard.tsx) (Feature UI), [`prisma/schema.prisma`](https://github.com/snapscoutza/codex-snapscout-build/blob/main/prisma/schema.prisma) (Data layer), [`app/api/auth/signup/route.ts`](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/auth/signup/route.ts) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App surfaces"]
  node_public_pages["Public site<br/>public routes<br/>[page.tsx]"]
  node_auth_pages["Auth flows<br/>auth routes<br/>[page.tsx]"]
  node_onboarding["Onboarding<br/>guided setup<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>authenticated area<br/>[page.tsx]"]
  node_crew_ops["Crew ops<br/>crew workflow<br/>[page.tsx]"]
  node_marketplace["Marketplace<br/>talent/jobs<br/>[page.tsx]"]
  node_profile_area["Profiles<br/>profile routes<br/>[page.tsx]"]
  node_admin_area["Admin tools<br/>ops console<br/>[page.tsx]"]
end

subgraph group_api["Server API"]
  node_api_auth[("Auth API<br/>route handlers<br/>[route.ts]")]
  node_api_crew[("Crew API<br/>route handlers<br/>[route.ts]")]
  node_api_market[("Marketplace API<br/>route handlers<br/>[route.ts]")]
  node_api_payments[("Payments API<br/>billing endpoints<br/>[route.ts]")]
end

subgraph group_shared["Shared logic"]
  node_auth_stack["Supabase auth<br/>identity boundary<br/>[client.ts]"]
  node_db_layer[("Data layer<br/>persistence<br/>[schema.prisma]")]
  node_billing_logic["Billing logic<br/>paystack integration<br/>[paystack.ts]"]
  node_onboarding_logic["Onboarding logic<br/>flow config"]
  node_email_system["Email system<br/>resend integration<br/>[send-email.tsx]"]
end

subgraph group_ui["UI system"]
  node_ui_components["Feature UI<br/>components<br/>[main-dashboard.tsx]"]
  node_core_ui["UI primitives<br/>design system<br/>[button.tsx]"]
end

node_root["Next.js app<br/>app shell<br/>[layout.tsx]"]

node_root -->|"serves"| node_public_pages
node_root -->|"serves"| node_auth_pages
node_root -->|"serves"| node_onboarding
node_root -->|"serves"| node_dashboard
node_root -->|"serves"| node_crew_ops
node_root -->|"serves"| node_marketplace
node_root -->|"serves"| node_profile_area
node_root -->|"serves"| node_admin_area
node_root -->|"routes"| node_api_auth
node_root -->|"routes"| node_api_crew
node_root -->|"routes"| node_api_market
node_root -->|"routes"| node_api_payments
node_auth_pages -->|"uses"| node_auth_stack
node_api_auth -->|"uses"| node_auth_stack
node_api_crew -->|"stores"| node_db_layer
node_api_market -->|"stores"| node_db_layer
node_api_payments -->|"delegates"| node_billing_logic
node_billing_logic -->|"updates"| node_db_layer
node_onboarding -->|"uses"| node_onboarding_logic
node_onboarding_logic -->|"writes"| node_db_layer
node_api_auth -->|"sends"| node_email_system
node_admin_area -->|"renders"| node_ui_components
node_marketplace -->|"renders"| node_ui_components
node_crew_ops -->|"renders"| node_ui_components
node_dashboard -->|"renders"| node_ui_components
node_public_pages -->|"composes"| node_core_ui
node_ui_components -->|"built on"| node_core_ui
node_auth_stack -->|"protects"| node_db_layer

click node_root "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/layout.tsx"
click node_public_pages "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/page.tsx"
click node_auth_pages "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/auth/login/page.tsx"
click node_onboarding "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/onboarding/page.tsx"
click node_dashboard "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/dashboard/page.tsx"
click node_crew_ops "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/(dashboard)/crew-pools/page.tsx"
click node_marketplace "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/marketplace/page.tsx"
click node_profile_area "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/profile/[id]/page.tsx"
click node_admin_area "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/admin/analytics/page.tsx"
click node_api_auth "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/auth/signup/route.ts"
click node_api_crew "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/crew-pools/route.ts"
click node_api_market "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/favorites/list/route.ts"
click node_api_payments "https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/paystack/initialize/route.ts"
click node_auth_stack "https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/supabase/client.ts"
click node_db_layer "https://github.com/snapscoutza/codex-snapscout-build/blob/main/prisma/schema.prisma"
click node_billing_logic "https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/paystack.ts"
click node_onboarding_logic "https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/onboarding-config.ts"
click node_email_system "https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/resend/send-email.tsx"
click node_ui_components "https://github.com/snapscoutza/codex-snapscout-build/blob/main/components/dashboard/main-dashboard.tsx"
click node_core_ui "https://github.com/snapscoutza/codex-snapscout-build/blob/main/components/ui/button.tsx"

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_public_pages,node_auth_pages,node_onboarding,node_dashboard,node_crew_ops,node_marketplace,node_profile_area,node_admin_area toneBlue
class node_api_auth,node_api_crew,node_api_market,node_api_payments toneAmber
class node_auth_stack,node_db_layer,node_billing_logic,node_onboarding_logic,node_email_system toneMint
class node_ui_components,node_core_ui toneRose
class node_root toneNeutral
```

## Components

### App surfaces

Next.js routes and user-facing product areas

- [Public site](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/page.tsx): public routes · Marketing, discovery, help, legal, and unauthenticated pages · `app/page.tsx`
- [Auth flows](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/auth/login/page.tsx): auth routes · Login, signup, verification, reset-password, and callback pages · `app/auth/login/page.tsx`
- [Onboarding](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/onboarding/page.tsx): guided setup · Staged account setup and completion flow for different personas · `app/onboarding/page.tsx`
- [Dashboard](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/dashboard/page.tsx): authenticated area · Protected user workspace for profile, payment, and subscription actions · `app/dashboard/page.tsx`
- [Crew ops](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/(dashboard)/crew-pools/page.tsx): crew workflow · Crew pools, availability, and call-sheet management · `app/(dashboard)/crew-pools/page.tsx`
- [Marketplace](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/marketplace/page.tsx): talent/jobs · Jobs, projects, applications, saved freelancers, and posting flows · `app/marketplace/page.tsx`
- [Profiles](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/profile/[id]/page.tsx): profile routes · Public profiles, profile setup, preview, and supporting pages · `app/profile/[id]/page.tsx`
- [Admin tools](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/admin/analytics/page.tsx): ops console · Analytics, schema debugging, email system, and database management pages · `app/admin/analytics/page.tsx`

### Server API

Route handlers and backend workflows inside the app

- [Auth API](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/auth/signup/route.ts): route handlers · Signup, callback, user registration, password reset, and email sending endpoints · `app/api/auth/signup/route.ts`
- [Crew API](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/crew-pools/route.ts): route handlers · Crew pools, members, availability requests, responses, and call sheets · `app/api/crew-pools/route.ts`
- [Marketplace API](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/favorites/list/route.ts): route handlers · Favorites, portfolio, and profile endpoints used by discovery and job flows · `app/api/favorites/list/route.ts`
- [Payments API](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/api/paystack/initialize/route.ts): billing endpoints · Paystack initialize, verify, subscribe, and webhook handlers · `app/api/paystack/initialize/route.ts`

### Shared logic

Cross-cutting libraries, contexts, hooks, and utilities

- [Supabase auth](https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/supabase/client.ts): identity boundary · Browser, server, middleware, and admin Supabase helpers for session and access control · `lib/supabase/client.ts`
- [Data layer](https://github.com/snapscoutza/codex-snapscout-build/blob/main/prisma/schema.prisma): persistence · Prisma schema plus database helpers and typed DB models · `prisma/schema.prisma`
- [Billing logic](https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/paystack.ts): paystack integration · Paystack client and webhook reconciliation into subscription records · `lib/paystack.ts`
- [Onboarding logic](https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/onboarding-config.ts): flow config · Onboarding configuration, validation, and profile bootstrap helpers · `lib/onboarding-config.ts`
- [Email system](https://github.com/snapscoutza/codex-snapscout-build/blob/main/lib/resend/send-email.tsx): resend integration · Resend configuration, email templates, and trigger/send helpers · `lib/resend/send-email.tsx`

### UI system

Reusable components and feature modules

- [Feature UI](https://github.com/snapscoutza/codex-snapscout-build/blob/main/components/dashboard/main-dashboard.tsx): components · Domain components for auth, dashboard, crew, marketplace, messaging, profile, and admin · `components/dashboard/main-dashboard.tsx`
- [UI primitives](https://github.com/snapscoutza/codex-snapscout-build/blob/main/components/ui/button.tsx): design system · Shared buttons, dialogs, inputs, menus, tabs, toasts, and layout primitives · `components/ui/button.tsx`

### Other components

- [Next.js app](https://github.com/snapscoutza/codex-snapscout-build/blob/main/app/layout.tsx): app shell · Single Next.js App Router codebase deployed as one application · `app/layout.tsx`

## Connections

- Next.js app → Public site: serves · Top-level public routes are part of the single app
- Next.js app → Auth flows: serves · Authentication pages live in the same Next.js tree
- Next.js app → Onboarding: serves · Guided setup is a first-class app surface
- Next.js app → Dashboard: serves · Authenticated workspace routes are hosted by the app
- Next.js app → Crew ops: serves · Crew management is a major product area
- Next.js app → Marketplace: serves · Marketplace discovery and posting routes are embedded in the app
- Next.js app → Profiles: serves · Profile pages and setup flows are part of the app
- Next.js app → Admin tools: serves · Operational admin pages are exposed in-app
- Next.js app → Auth API: routes · Serverless auth endpoints are defined under app/api
- Next.js app → Crew API: routes · Crew workflow endpoints are exposed as route handlers
- Next.js app → Marketplace API: routes · Marketplace-related backend endpoints live in the app
- Next.js app → Payments API: routes · Billing endpoints are implemented as serverless handlers
- Auth flows → Supabase auth: uses · Login and signup flows depend on Supabase session handling
- Auth API → Supabase auth: uses · Auth endpoints validate and mutate identity state through Supabase
- Crew API → Data layer: stores · Crew pools, members, availability, and call sheets persist to the database
- Marketplace API → Data layer: stores · Profile, portfolio, and favorites data are persisted through the data layer
- Payments API → Billing logic: delegates · Paystack handlers rely on shared billing reconciliation logic
- Billing logic → Data layer: updates · Subscription state is written back to persistent records
- Onboarding → Onboarding logic: uses · Onboarding screens are driven by shared step configuration and validation
- Onboarding logic → Data layer: writes · Completed setup populates profile and account records
- Auth API → Email system: sends · Auth flows trigger verification and reset emails
- Admin tools → Feature UI: renders · Admin screens are composed from reusable feature components
- Marketplace → Feature UI: renders · Marketplace pages are assembled from shared feature modules
- Crew ops → Feature UI: renders · Crew pool and availability screens reuse specialized components
- Dashboard → Feature UI: renders · Dashboard pages are built from composable feature widgets
- Public site → UI primitives: composes · Public pages rely on shared design-system primitives
- Feature UI → UI primitives: built on · Feature modules are implemented with the base UI system
- Supabase auth → Data layer: protects · Identity boundary gates database access and privileged operations
