How ojus4/solvo-claude-platform works
This repository is a single Next.js application that combines public marketing pages, authenticated user flows, an admin area, and a set of server-side API routes. The overall architecture is a monolith deployed on Vercel, with Supabase used as the backend data/auth layer and static JSON files used for some read-only domain data.
High-level shape
The app is organized around three user-facing zones:
1. Public and auth entry points
- Landing page at app/page.tsx
- Login/signup/access pages under app/(auth)/...
- Auth error and suspended states under app/auth/auth-error and app/suspended
2. Authenticated dashboard
- Dashboard page under app/(dashboard)/dashboard/page.tsx
- Dashboard data fetched through app/api/dashboard/data/route.ts
3. Admin and operational endpoints
- Admin promotions page under app/admin/promotions/page.tsx
- Admin-only backend route app/api/admin/applications/route.ts
- Supporting payment, assessment, psychometric, roadmap, PDF, and waitlist APIs
This is not a pure frontend app; the architecture is a mixed client/server React app with a substantial backend surface in Next.js route handlers.
Core technology boundaries
Frontend runtime
• Next.js App Router drives page routing and server/client composition.
• React components are split across route groups and shared component/provider utilities.
• Tailwind/PostCSS/global CSS provide the styling layer.
• components/providers.tsx suggests app-wide context providers are centralized there.
Backend runtime
• Next.js route handlers under app/api/**/route.ts are the main backend interface.
• The app uses server-side Supabase clients for secure data access and auth/session handling.
• There is a dedicated Supabase admin client for elevated operations, separated from regular user-scoped clients.
Data and integration layer
• Supabase is the main external system for identity and app data.
- lib/supabase/client.ts for browser-side access
- lib/supabase/server.ts for server-side requests
- lib/supabase/middleware-client.ts for middleware/session bridging
- lib/supabase/admin-client.ts for privileged operations
• Email delivery is abstracted in lib/email/send.ts.
• PDF generation is exposed through an API route, implying server-side document creation.
• Static domain datasets live in public/data/ and are part of the application’s read model:
- job_trends.json
- skills.json
- career roadmaps under public/data/roadmaps/*.json
Main subsystems
1. Authentication and session control
Auth is handled through a combination of route pages, callback endpoints, Supabase clients, and middleware.
Key pieces:
• Login and signup pages in app/(auth)/login and app/(auth)/signup
• Access/invitation page in app/(auth)/access/[slug]
• Auth callback route(s) in:
- app/(auth)/auth/callback/route.ts
- app/api/auth/callback/route.ts
• Sign-out route in app/api/auth/signout/route.ts
• Middleware in middleware.ts
The middleware likely enforces:
• authenticated access to dashboard/admin areas
• session refresh or token propagation
• redirect handling for suspended/unauthorized users
The presence of app/suspended/page.tsx suggests there is an account status gate beyond basic login, likely based on user metadata or application state.
2. User dashboard
The dashboard is a protected user area with its own data endpoint.
Flow:
• User lands on app/(dashboard)/dashboard/page.tsx
• Page fetches consolidated data from app/api/dashboard/data/route.ts
• The route likely aggregates account/profile, assessment, roadmap, payment, or application status from Supabase and returns a dashboard-ready shape
This separation indicates the UI is not directly querying many backend sources itself; instead, the dashboard consumes a single backend composition endpoint.
3. Assessment and psychometric flows
There are two adjacent but distinct feature areas:
• app/api/assessment/complete/route.ts
• app/api/psychometric/submit/route.ts
• app/api/psychometric/results/route.ts
This suggests the product collects assessment inputs, stores them server-side, and later exposes computed results. The distinction between “assessment” and “psychometric” implies:
• one flow may finalize completion state
• the other may handle questionnaire responses and derived results
These routes likely write to Supabase and return derived scoring or eligibility data used elsewhere in the app.
4. Roadmap/content delivery
Career roadmap content is modeled as route-driven dynamic lookup plus static JSON backing data.
Key pieces:
• app/api/roadmap/[career]/route.ts
• static files in public/data/roadmaps/
This is a strong architectural boundary: roadmap content appears to be delivered from versioned static data rather than a database-heavy CMS. The API route likely normalizes and serves roadmap data for a given career key, using the public JSON assets as the source of truth.
5. Payments and entitlement flow
Payment is a first-class subsystem with multiple steps exposed as separate API routes:
• app/api/payments/create-order/route.ts
• app/api/payments/verify/route.ts
• app/api/payments/webhook/route.ts
• app/api/payments/apply/route.ts
This indicates a multi-stage payment lifecycle:
1. create an order
2. verify client-side or provider-side confirmation
3. accept asynchronous webhook events
4. apply the payment outcome to the user/account state
Because there is both verification and webhook handling, the payment system is designed to treat synchronous client confirmation and asynchronous provider callbacks as separate trust boundaries. The apply route likely turns a successful payment into a product entitlement, promotion, or access change.
6. Admin operations
Admin functionality is separated into both UI and privileged backend access.
UI:
• app/admin/promotions/page.tsx
Backend:
• app/api/admin/applications/route.ts
Supporting authorization:
• lib/admin/permissions.ts
This suggests admin access is role-based and enforced in server code, not just by hiding the UI. The permissions helper likely centralizes checks against Supabase user metadata or application-specific role fields. The admin application route probably uses the privileged Supabase admin client to inspect or update sensitive records.
7. Waitlist and lead capture
There is a dedicated waitlist endpoint:
• app/api/waitlist/join/route.ts
This is likely a low-friction public write path for collecting prospective users before full account activation or access approval. It may feed into email notifications or admin review.
8. Document generation
The app includes:
• app/api/pdf/generate/route.ts
This indicates server-side generation of downloadable documents, likely tied to assessments, reports, or application summaries. Since it is a route handler, the PDF output is produced on demand rather than stored permanently in the client.
9. Shared client-side state and hooks
There is a small but important client abstraction layer in lib/:
• lib/hooks/useUser.ts
• lib/hooks/useSiteConfig.ts
• lib/store/userStore.ts
These indicate the UI uses shared client state for user/session data and site configuration. The presence of a user store suggests the app avoids repeatedly fetching identity state in individual components and instead centralizes it in a client-side store.
10. Utilities and notifications
• lib/email/send.ts handles outbound email
• lib/utils.ts is a general utility layer
• types/index.ts provides shared type definitions across frontend and backend boundaries
Important request/data flows
Auth flow
1. User hits login/signup/access pages.
2. Supabase authentication completes through callback handling.
3. Callback route writes/refreshes session state.
4. Middleware and server routes use Supabase server/middleware clients to enforce access.
5. Unauthorized or blocked users are redirected to auth error or suspended states.
Dashboard flow
1. Authenticated user opens the dashboard.
2. Dashboard page calls the dashboard data API.
3. API aggregates user data from Supabase and any derived state from assessment/payment/roadmap records.
4. Page renders a single composed view.
Assessment/psychometric flow
1. User submits questionnaire or assessment data.
2. Route handler validates and stores submissions.
3. A results endpoint returns calculated outputs.
4. Those results likely feed dashboard display, PDF generation, or application eligibility.
Payment flow
1. Client requests an order.
2. Payment provider confirmation is verified.
3. Webhook updates authoritative payment state.
4. Apply route converts payment state into access/entitlement changes.
5. Dashboard/admin surfaces the resulting status.
Roadmap/content flow
1. Client requests a career roadmap by slug.
2. Dynamic route loads the relevant roadmap definition.
3. Static JSON under public/data/roadmaps provides the canonical content.
4. UI renders the roadmap without needing a database write path.
Admin flow
1. Admin lands on promotions page.
2. Server-side permission checks determine access.
3. Admin route uses the Supabase admin client for elevated reads/writes.
4. Sensitive application changes are applied through server-only code.
Architectural boundaries to capture in a diagram
If you are drawing this repository, the most important boundaries are:
• Browser/UI boundary
- pages, route groups, client hooks, provider/store layer
• Next.js server boundary
- route handlers, server components, middleware, auth callbacks
• Supabase boundary
- standard user client vs server client vs middleware client vs admin client
• External integration boundary
- payment provider via create/verify/webhook
- email delivery via lib/email/send.ts
- PDF generation as a server-side output path
• Static content boundary
- career roadmaps, job trends, and skill datasets in public/data
Repository-level interpretation
This repo is best understood as a product platform for career or assessment-driven access management:
• public users sign up or join a waitlist
• authenticated users view a dashboard and assessment/roadmap content
• payments unlock or apply access
• admins manage applications/promotions
• Supabase stores identity and application state
• Next.js route handlers provide the server orchestration layer
In short: a Next.js/Supabase application with clear separation between public acquisition, authenticated user experience, admin operations, and server-side orchestration for payments, assessments, documents, and content delivery.
Main entry points: supabase Supabase clients · layout.tsx App shell · providers.tsx Providers · route.ts Admin API
Components 24
Frontend
App Router pages, shared UI, and client state
- App shell · Root layout and global styling for the app
solvo-platform/app/layout.tsx - Landing · Public entry page
solvo-platform/app/page.tsx - Auth pages · Login, signup, access, auth error, and suspended views
solvo-platform/app/(auth) - Dashboard · Authenticated user dashboard view
solvo-platform/app/(dashboard)/dashboard/page.tsx - Admin promo · Admin promotions interface
solvo-platform/app/admin/promotions/page.tsx - Providers · App-wide provider composition
solvo-platform/components/providers.tsx - User hook · Client-side user/session access
solvo-platform/lib/hooks/useUser.ts - Site config · Client-side site configuration access
solvo-platform/lib/hooks/useSiteConfig.ts - User store · Shared user state container
solvo-platform/lib/store/userStore.ts
Backend
Route handlers, middleware, and server-side orchestration
- Middleware · Session and access control at the edge
solvo-platform/middleware.ts - Auth routes · Auth callback and sign-out handlers
solvo-platform/app/api/auth - Dashboard API · Aggregated dashboard data endpoint
solvo-platform/app/api/dashboard/data/route.ts - Admin API · Admin applications backend endpoint
solvo-platform/app/api/admin/applications/route.ts - Assessment API · Assessment completion endpoint
solvo-platform/app/api/assessment/complete/route.ts - Psychometric API · Submit and results endpoints for psychometric flows
solvo-platform/app/api/psychometric - Payments API · Order creation, verification, webhook, and apply flow
solvo-platform/app/api/payments - Roadmap API · Career roadmap lookup endpoint
solvo-platform/app/api/roadmap/[career]/route.ts - Waitlist API · Public waitlist join endpoint
solvo-platform/app/api/waitlist/join/route.ts - PDF API · Server-side PDF generation endpoint
solvo-platform/app/api/pdf/generate/route.ts
Data & Integrations
Supabase, static content, email, and generated outputs
- Supabase clients · Browser, server, middleware, and admin Supabase clients
solvo-platform/lib/supabase - Permissions · Admin authorization checks
solvo-platform/lib/admin/permissions.ts - Email send · Outbound email delivery helper
solvo-platform/lib/email/send.ts - Static data · Roadmaps, skills, and job trend datasets
solvo-platform/public/data - Shared types · Cross-layer TypeScript contracts
solvo-platform/types/index.ts
Connections 27
- App shell → Providers: wraps · Global providers compose inside the root shell
- App shell → Landing: hosts · Root route renders the landing page
- App shell → Auth pages: hosts · App Router route group for public auth pages
- App shell → Dashboard: hosts · Protected dashboard lives in the app shell
- App shell → Admin promo: hosts · Admin UI renders under the same shell
- Providers → User store: composes · Providers likely initialize shared user state
- Providers → User hook: supports · Hooks consume app-level context
- Providers → Site config: supports · Hooks consume app-level context
- Middleware → Supabase clients: uses · Middleware uses the session-aware Supabase client
- Auth pages → Auth routes: calls · Auth UI relies on callback and sign-out routes
- Auth routes → Supabase clients: authenticates · Auth handlers persist and refresh sessions
- Middleware → Auth pages: guards · Redirects or gates protected and suspended states
- Dashboard → Dashboard API: loads · Dashboard consumes one aggregated data endpoint
- Dashboard API → Supabase clients: reads · Backend data composition comes from Supabase
- Admin promo → Admin API: administers · Admin UI drives privileged application actions
- Admin API → Permissions: checks · Server-side role validation before sensitive actions
- Admin API → Supabase clients: writes · Privileged access uses the admin Supabase client
- Assessment API → Supabase clients: stores · Assessment completion persists server-side state
- Psychometric API → Supabase clients: stores · Submission and results use Supabase-backed state
- Payments API → Supabase clients: updates · Payment state is recorded and applied server-side
- Payments API → Email send: notifies · Payment lifecycle may trigger email delivery
- Roadmap API → Static data: serves · Career roadmaps are read from static JSON assets
- Waitlist API → Email send: notifies · Waitlist signup can trigger outbound email
- PDF API → Supabase clients: reads · PDF generation likely uses stored user or report data
- Dashboard API → Shared types: shapes · Shared contracts define response payloads
- Admin API → Shared types: shapes · Shared contracts define admin data shapes
- Psychometric API → Shared types: shapes · Shared contracts define scoring/result payloads