How snapscoutza/codex-snapscout-build works
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: layout.tsx Next.js app · main-dashboard.tsx Feature UI · schema.prisma Data layer · route.ts Auth API
Components 20
App surfaces
Next.js routes and user-facing product areas
- Public site · Marketing, discovery, help, legal, and unauthenticated pages
app/page.tsx - Auth flows · Login, signup, verification, reset-password, and callback pages
app/auth/login/page.tsx - Onboarding · Staged account setup and completion flow for different personas
app/onboarding/page.tsx - Dashboard · Protected user workspace for profile, payment, and subscription actions
app/dashboard/page.tsx - Crew ops · Crew pools, availability, and call-sheet management
app/(dashboard)/crew-pools/page.tsx - Marketplace · Jobs, projects, applications, saved freelancers, and posting flows
app/marketplace/page.tsx - Profiles · Public profiles, profile setup, preview, and supporting pages
app/profile/[id]/page.tsx - Admin tools · 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 · Signup, callback, user registration, password reset, and email sending endpoints
app/api/auth/signup/route.ts - Crew API · Crew pools, members, availability requests, responses, and call sheets
app/api/crew-pools/route.ts - Marketplace API · Favorites, portfolio, and profile endpoints used by discovery and job flows
app/api/favorites/list/route.ts - Payments API · Paystack initialize, verify, subscribe, and webhook handlers
app/api/paystack/initialize/route.ts
Shared logic
Cross-cutting libraries, contexts, hooks, and utilities
- Supabase auth · Browser, server, middleware, and admin Supabase helpers for session and access control
lib/supabase/client.ts - Data layer · Prisma schema plus database helpers and typed DB models
prisma/schema.prisma - Billing logic · Paystack client and webhook reconciliation into subscription records
lib/paystack.ts - Onboarding logic · Onboarding configuration, validation, and profile bootstrap helpers
lib/onboarding-config.ts - Email system · Resend configuration, email templates, and trigger/send helpers
lib/resend/send-email.tsx
UI system
Reusable components and feature modules
- Feature UI · Domain components for auth, dashboard, crew, marketplace, messaging, profile, and admin
components/dashboard/main-dashboard.tsx - UI primitives · Shared buttons, dialogs, inputs, menus, tabs, toasts, and layout primitives
components/ui/button.tsx
Other components
- Next.js app · Single Next.js App Router codebase deployed as one application
app/layout.tsx
Connections 28
- 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