# jeetendrapatel5/client-portal architecture

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

- Interactive diagram: https://gitdiagram.com/jeetendrapatel5/client-portal
- Repository: https://github.com/jeetendrapatel5/client-portal

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with three main surfaces: a **public marketing site**, an **authenticated dashboard**, and a **tokenized client portal**.  
   - The codebase is organized by route in `app/`, with shared UI in `components/` and server-side integrations in `lib/`.

2. **Primary user-facing areas**
   - `app/page.jsx` and `components/landing/*` power the landing/marketing experience.
   - `app/dashboard/*` is the internal workspace for managing projects, clients, invoices, milestones, and settings.
   - `app/portal/[token]` is a client-facing delivery/approval portal accessed via a secure token.
   - `app/showcase/[slug]` and `app/u/[username]` expose public-facing portfolio/profile pages.

3. **Authentication and access control**
   - Authentication is handled through `app/api/auth/[...nextauth]/route.js` plus a separate signup route.
   - `lib/auth.js`, `lib/middleware.ts`, and `proxy.js` indicate route protection and session-aware access control.
   - The dashboard and admin-style APIs are protected; the portal uses token-based access instead of normal account login.

4. **API-first backend inside the same app**
   - Most business operations are exposed as route handlers under `app/api/*`.
   - These APIs cover **projects, milestones, invoices, files, inquiries, updates, settings, users/profile**, and portal actions.
   - The front-end components in `components/dashboard/*`, `components/project/*`, and `components/portal/*` likely call these routes directly for mutations and data refreshes.

5. **Core domain model**
   - The central entities are **projects**, **milestones**, **invoices**, **files**, **updates**, **inquiries**, and **user/profile settings**.
   - Projects appear to be the hub object: they own files, story content, updates, cover images, milestones, and publish state.
   - Milestones have richer workflow support: reorder, delivery updates, approval/rejection logic, and update feeds.

6. **Persistent storage layer**
   - `prisma/schema.prisma` and the migration history show that **Prisma** is the main database layer.
   - The schema evolved to support project management, file storage metadata, milestone updates/messages, invoices, showcase pages, profile data, approval logic, and payment-link uniqueness.
   - The database is the source of truth for workflow state; UI state is mostly derived from it.

7. **File and media handling**
   - File uploads are handled through `app/api/files` and project-specific file routes, with `lib/cloudinary.js` indicating **Cloudinary** is used for storage/media delivery.
   - Separate routes exist for project cover images and story cover images, showing media is attached to multiple content types.
   - The portal has file preview/download experiences, so file metadata in the DB and binary assets in Cloudinary are split concerns.

8. **Notifications and email workflows**
   - `lib/email.js`, `lib/emailTemplates.js`, and `emails/MilestoneUpdateEmail.jsx` show a templated email subsystem.
   - Milestone updates and reminder-related flows are first-class, with a dedicated cron endpoint at `app/api/cron/reminders/route.js`.
   - This suggests asynchronous notification behavior driven by scheduled execution rather than only user-triggered actions.

9. **Payments and invoicing**
   - Invoices are managed through dedicated API routes and dashboard views.
   - `app/api/webhooks/stripe/route.js` shows **Stripe** integration for payment event handling.
   - The payment-link migrations and invoice-related components indicate invoice/payment status is synchronized between Stripe events and the local database.

10. **Client approval and delivery workflow**
   - The portal token routes and `app/api/portal/[token]/approve` support a shareable approval flow for clients.
   - Milestones and project delivery artifacts feed into portal UI components such as progress banners, milestone feeds, sign-off panels, and deliverable lists.
   - This is a key boundary: internal users manage work in the dashboard, while clients review and approve via the portal.

11. **Project content and publishing**
   - Project-specific routes include publish/unpublish, story editing, story cover uploads, updates, and inquiry handling.
   - This indicates a second workflow beyond internal management: projects can be transformed into public showcase content.
   - The showcasе pages and public profile routes likely consume published project/story data from the same database.

12. **Shared UI and layout structure**
   - Reusable UI primitives live in `components/ui/*`, while feature-specific components are grouped by domain (`dashboard`, `portal`, `project`, `landing`).
   - Layouts in `app/layout.tsx`, `app/dashboard/layout.jsx`, and `app/settings/layout.jsx` define separate shells for public, authenticated, and settings areas.
   - This separation matters architecturally because the app has multiple distinct experiences built on the same backend.

13. **Infrastructure and deployment signals**
   - The presence of `vercel.json`, Next.js app routing, and server route handlers suggests deployment is optimized for **Vercel**.
   - This is a serverless-style architecture: route handlers, webhook endpoints, and cron-like scheduled routes run within the platform rather than a separate backend service.

14. **Main data flow to diagram**
   - User actions in the dashboard/portal trigger API route handlers.
   - Route handlers read/write Prisma models in the database.
   - Some mutations also fan out to Cloudinary, Stripe, or email delivery.
   - Scheduled reminder jobs and webhook callbacks update the same database, which then drives the dashboard, portal, and public pages.

Main entry points: [`app/dashboard/page.jsx`](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/page.jsx) (Dashboard shell), [`app/api/projects/route.js`](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/projects/route.js) (Projects API), [`lib/prisma.js`](https://github.com/jeetendrapatel5/client-portal/blob/main/lib/prisma.js) (Prisma layer), [`app/api/milestones/route.js`](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/milestones/route.js) (Milestones API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public surfaces"]
  node_node_landing["Landing page<br/>public marketing<br/>[page.jsx]"]
  node_node_showcase["Showcase pages<br/>public portfolio<br/>[page.jsx]"]
  node_node_profile["Profile pages<br/>public profile<br/>[page.jsx]"]
end

subgraph group_group_app["Authenticated app"]
  node_node_dashboard["Dashboard shell<br/>internal workspace<br/>[page.jsx]"]
  node_node_dashboard_projects["Projects<br/>dashboard module<br/>[page.jsx]"]
  node_node_dashboard_story["Story editor<br/>content editor<br/>[page.jsx]"]
  node_node_dashboard_invoices["Invoices<br/>billing module<br/>[page.jsx]"]
  node_node_dashboard_clients["Clients<br/>client management<br/>[page.jsx]"]
  node_node_settings["Settings<br/>[page.jsx]"]
end

subgraph group_group_portal["Client portal"]
  node_node_portal["Client portal<br/>token portal<br/>[page.jsx]"]
end

subgraph group_group_api["API backend"]
  node_node_auth["Auth routes<br/>session auth<br/>[route.js]"]
  node_node_api_projects["Projects API<br/>project CRUD<br/>[route.js]"]
  node_node_api_milestones["Milestones API<br/>workflow API<br/>[route.js]"]
  node_node_api_invoices["Invoices API<br/>billing API<br/>[route.js]"]
  node_node_api_portal["Portal API<br/>approval API<br/>[route.js]"]
  node_node_api_files["Files API<br/>media API<br/>[route.js]"]
  node_node_api_webhooks["Webhooks & cron<br/>async handlers<br/>[route.js]"]
end

subgraph group_group_lib["Shared services"]
  node_node_lib_auth["Auth guard<br/>route protection<br/>[middleware.ts]"]
  node_node_lib_prisma[("Prisma layer<br/>database client<br/>[prisma.js]")]
  node_node_lib_media["Media storage<br/>cloudinary integration<br/>[cloudinary.js]"]
  node_node_lib_email["Email system<br/>notification service<br/>[email.js]"]
end

subgraph group_group_data["Persistence"]
end

node_node_landing -->|"lead form / inquiries"| node_node_api_projects
node_node_dashboard -->|"opens"| node_node_dashboard_projects
node_node_dashboard -->|"opens"| node_node_dashboard_invoices
node_node_dashboard -->|"opens"| node_node_dashboard_clients
node_node_dashboard -->|"opens"| node_node_settings
node_node_dashboard_projects -->|"edits"| node_node_dashboard_story
node_node_portal -->|"approves"| node_node_api_portal
node_node_dashboard -->|"manage projects"| node_node_api_projects
node_node_dashboard_projects -->|"CRUD"| node_node_api_projects
node_node_dashboard_story -->|"save story"| node_node_api_projects
node_node_dashboard -->|"workflow"| node_node_api_milestones
node_node_portal -->|"review updates"| node_node_api_milestones
node_node_dashboard_invoices -->|"CRUD"| node_node_api_invoices
node_node_dashboard -->|"uploads"| node_node_api_files
node_node_api_projects -->|"store media"| node_node_lib_media
node_node_api_files -->|"store media"| node_node_lib_media
node_node_api_projects -->|"reads/writes"| node_node_lib_prisma
node_node_api_milestones -->|"reads/writes"| node_node_lib_prisma
node_node_api_invoices -->|"reads/writes"| node_node_lib_prisma
node_node_api_portal -->|"reads/writes"| node_node_lib_prisma
node_node_api_webhooks -->|"syncs events"| node_node_lib_prisma
node_node_api_webhooks -->|"sends notifications"| node_node_lib_email
node_node_auth -->|"protects routes"| node_node_lib_auth
node_node_api_projects -->|"authenticated"| node_node_auth
node_node_api_invoices -->|"authenticated"| node_node_auth
node_node_api_milestones -->|"authenticated"| node_node_auth
node_node_api_portal -->|"powers"| node_node_portal
node_node_showcase -->|"reads published data"| node_node_lib_prisma
node_node_profile -->|"reads profile data"| node_node_lib_prisma

click node_node_landing "https://github.com/jeetendrapatel5/client-portal/blob/main/app/page.jsx"
click node_node_showcase "https://github.com/jeetendrapatel5/client-portal/blob/main/app/showcase/[slug]/page.jsx"
click node_node_profile "https://github.com/jeetendrapatel5/client-portal/blob/main/app/u/[username]/page.jsx"
click node_node_dashboard "https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/page.jsx"
click node_node_dashboard_projects "https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/projects/page.jsx"
click node_node_dashboard_story "https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/projects/[id]/story/page.jsx"
click node_node_dashboard_invoices "https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/invoices/page.jsx"
click node_node_dashboard_clients "https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/clients/page.jsx"
click node_node_settings "https://github.com/jeetendrapatel5/client-portal/blob/main/app/settings/page.jsx"
click node_node_portal "https://github.com/jeetendrapatel5/client-portal/blob/main/app/portal/[token]/page.jsx"
click node_node_auth "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/auth/[...nextauth]/route.js"
click node_node_api_projects "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/projects/route.js"
click node_node_api_milestones "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/milestones/route.js"
click node_node_api_invoices "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/invoices/route.js"
click node_node_api_portal "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/portal/[token]/approve/route.js"
click node_node_api_files "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/files/route.js"
click node_node_api_webhooks "https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/webhooks/stripe/route.js"
click node_node_lib_auth "https://github.com/jeetendrapatel5/client-portal/blob/main/lib/middleware.ts"
click node_node_lib_prisma "https://github.com/jeetendrapatel5/client-portal/blob/main/lib/prisma.js"
click node_node_lib_media "https://github.com/jeetendrapatel5/client-portal/blob/main/lib/cloudinary.js"
click node_node_lib_email "https://github.com/jeetendrapatel5/client-portal/blob/main/lib/email.js"

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_node_landing,node_node_showcase,node_node_profile toneBlue
class node_node_dashboard,node_node_dashboard_projects,node_node_dashboard_story,node_node_dashboard_invoices,node_node_dashboard_clients,node_node_settings toneAmber
class node_node_portal toneMint
class node_node_auth,node_node_api_projects,node_node_api_milestones,node_node_api_invoices,node_node_api_portal,node_node_api_files,node_node_api_webhooks toneRose
class node_node_lib_auth,node_node_lib_prisma,node_node_lib_media,node_node_lib_email toneIndigo
```

## Components

### Public surfaces

Marketing, showcase, and profile pages exposed without dashboard access.

- [Landing page](https://github.com/jeetendrapatel5/client-portal/blob/main/app/page.jsx): public marketing · Home/marketing experience powered by the landing components. · `app/page.jsx`
- [Showcase pages](https://github.com/jeetendrapatel5/client-portal/blob/main/app/showcase/[slug]/page.jsx): public portfolio · Published project/story pages rendered from shared project data. · `app/showcase/[slug]/page.jsx`
- [Profile pages](https://github.com/jeetendrapatel5/client-portal/blob/main/app/u/[username]/page.jsx): public profile · Public user profile pages. · `app/u/[username]/page.jsx`

### Authenticated app

Dashboard and settings shells for internal users.

- [Dashboard shell](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/page.jsx): internal workspace · Main authenticated workspace for managing clients, projects, and invoices. · `app/dashboard/page.jsx`
- [Projects](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/projects/page.jsx): dashboard module · Project listing and detail views for workspace management. · `app/dashboard/projects/page.jsx`
- [Story editor](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/projects/[id]/story/page.jsx): content editor · Project story editing surface inside the dashboard. · `app/dashboard/projects/[id]/story/page.jsx`
- [Invoices](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/invoices/page.jsx): billing module · Invoice management views in the authenticated workspace. · `app/dashboard/invoices/page.jsx`
- [Clients](https://github.com/jeetendrapatel5/client-portal/blob/main/app/dashboard/clients/page.jsx): client management · Client-facing management views in the dashboard. · `app/dashboard/clients/page.jsx`
- [Settings](https://github.com/jeetendrapatel5/client-portal/blob/main/app/settings/page.jsx): account settings · Settings area and separate settings shell. · `app/settings/page.jsx`

### Client portal

Token-based delivery and approval experience for clients.

- [Client portal](https://github.com/jeetendrapatel5/client-portal/blob/main/app/portal/[token]/page.jsx): token portal · Tokenized client portal for review, delivery, and approval. · `app/portal/[token]/page.jsx`

### API backend

Route handlers implementing the app's business operations.

- [Auth routes](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/auth/[...nextauth]/route.js): session auth · NextAuth signin/session flow and signup route. · `app/api/auth/[...nextauth]/route.js`
- [Projects API](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/projects/route.js): project CRUD · Project lifecycle, publish flow, covers, story, files, updates, and inquiries. · `app/api/projects/route.js`
- [Milestones API](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/milestones/route.js): workflow API · Milestone CRUD, reordering, and milestone update endpoints. · `app/api/milestones/route.js`
- [Invoices API](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/invoices/route.js): billing API · Invoice CRUD and payment-link related operations. · `app/api/invoices/route.js`
- [Portal API](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/portal/[token]/approve/route.js): approval API · Token-based portal access and approval actions. · `app/api/portal/[token]/approve/route.js`
- [Files API](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/files/route.js): media API · Upload and project file management endpoints. · `app/api/files/route.js`
- [Webhooks & cron](https://github.com/jeetendrapatel5/client-portal/blob/main/app/api/webhooks/stripe/route.js): async handlers · Stripe webhook processing and scheduled reminder jobs. · `app/api/webhooks/stripe/route.js`

### Shared services

Auth, persistence, media, email, and utility integrations.

- [Auth guard](https://github.com/jeetendrapatel5/client-portal/blob/main/lib/middleware.ts): route protection · Session-aware middleware and auth helpers protecting internal routes. · `lib/middleware.ts`
- [Prisma layer](https://github.com/jeetendrapatel5/client-portal/blob/main/lib/prisma.js): database client · Prisma client and schema-backed persistence layer. · `lib/prisma.js`
- [Media storage](https://github.com/jeetendrapatel5/client-portal/blob/main/lib/cloudinary.js): cloudinary integration · Cloudinary-backed file and image storage. · `lib/cloudinary.js`
- [Email system](https://github.com/jeetendrapatel5/client-portal/blob/main/lib/email.js): notification service · Templated email delivery for milestone updates and reminders. · `lib/email.js`

## Connections

- Landing page → Projects API: lead form / inquiries · Marketing interactions submit inquiries and project-related requests.
- Dashboard shell → Projects: opens · Dashboard routes into project management.
- Dashboard shell → Invoices: opens · Dashboard routes into billing management.
- Dashboard shell → Clients: opens · Dashboard routes into client management.
- Dashboard shell → Settings: opens · Dashboard routes into account settings.
- Projects → Story editor: edits · Project detail surfaces project story editing.
- Client portal → Portal API: approves · Portal approval actions are handled by tokenized API routes.
- Dashboard shell → Projects API: manage projects · Authenticated workspace performs project mutations through the API.
- Projects → Projects API: CRUD · Project views call project route handlers for data mutations and refresh.
- Story editor → Projects API: save story · Story editor persists project story content and cover media.
- Dashboard shell → Milestones API: workflow · Milestone management uses dedicated workflow endpoints.
- Client portal → Milestones API: review updates · Portal consumes milestone delivery and approval state.
- Invoices → Invoices API: CRUD · Invoice UI reads and writes invoice records.
- Dashboard shell → Files API: uploads · Dashboard file actions use file upload endpoints.
- Projects API → Media storage: store media · Project covers, story covers, and attachments are stored externally.
- Files API → Media storage: store media · Uploaded files are persisted through media storage.
- Projects API → Prisma layer: reads/writes · Project business state is persisted in the database.
- Milestones API → Prisma layer: reads/writes · Milestone state, ordering, updates, and approvals are stored in Prisma models.
- Invoices API → Prisma layer: reads/writes · Invoices and payment-link state are stored locally.
- Portal API → Prisma layer: reads/writes · Token access and approval state are resolved through the database.
- Webhooks & cron → Prisma layer: syncs events · Stripe and reminder jobs update the same source of truth.
- Webhooks & cron → Email system: sends notifications · Scheduled reminders and workflow events trigger email delivery.
- Auth routes → Auth guard: protects routes · Session and middleware helpers enforce access control.
- Projects API → Auth routes: authenticated · Project APIs rely on login/session boundaries.
- Invoices API → Auth routes: authenticated · Invoice APIs are protected by auth.
- Milestones API → Auth routes: authenticated · Milestone APIs are protected by auth.
- Portal API → Client portal: powers · Token portal UI is backed by portal-specific API routes.
- Showcase pages → Prisma layer: reads published data · Public showcase pages render from the shared database models.
- Profile pages → Prisma layer: reads profile data · Public profile pages render from persisted user/profile data.
