# sumitverma77/plinth-platform architecture

> Architecture diagram of the GitHub repository sumitverma77/plinth-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sumitverma77/plinth-platform
- Repository: https://github.com/sumitverma77/plinth-platform

## Overview

Plinth is a portfolio-building control plane: people sign in, create a portfolio, edit its workspace in the Web IDE, preview changes, and publish. The Next.js admin communicates with a NestJS API; a separate worker consumes background queues and integrates with GitHub. The graph preserves documented billing, integration catalogue, AI copilot, and administration capabilities. Some subsystem links are based on the README or SOURCE INDEX references; unsampled implementations and their internal call paths are not inferred.

Main entry points: [`admin/lib/api.ts`](https://github.com/sumitverma77/plinth-platform/blob/main/admin/lib/api.ts) (API client), [`backend/src`](https://github.com/sumitverma77/plinth-platform/tree/main/backend/src) (Background worker), [`backend/src/provisioning/portfolios.service.ts`](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/provisioning/portfolios.service.ts) (Provisioning), [`backend/src/sandbox/preview.service.ts`](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/sandbox/preview.service.ts) (Preview lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_admin_web["Next.js admin"]
  node_api_client["API client<br/>[api.ts]"]
  node_preview_ui["Preview controls<br/>[usePreview.ts]"]
end

subgraph group_identity["Identity and account"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_auth_routes["Auth routes<br/>[auth.controller.ts]"]
end

subgraph group_portfolio["Portfolio lifecycle"]
  node_portfolio_setup["Portfolio setup"]
  node_provisioning["Provisioning"]
  node_workspace["Workspace editing"]
  node_operations["Edit operations"]
  node_preview_routes["Preview routes"]
  node_preview["Preview lifecycle<br/>[preview.service.ts]"]
  node_publish["Publish"]
  node_copilot["AI copilot"]
end

subgraph group_platform["Platform services"]
  node_catalogue["Integration catalogue"]
  node_billing["Billing"]
  node_admin_tools["Admin tools"]
  node_legal["Legal requests"]
  node_worker["Background worker"]
end

subgraph group_data["Persistence and queues"]
  node_postgres[("PostgreSQL<br/>[prisma.service.ts]")]
  node_queues["Background queues<br/>[queue.module.ts]"]
end

node_user(("Portfolio builder"))
node_github["GitHub"]
node_hosting["Vercel hosting"]

node_user -->|"uses"| node_admin_web
node_admin_web -->|"requests through"| node_api_client
node_api_client -->|"sends HTTP requests"| node_auth_routes
node_auth_routes -->|"delegates to"| node_auth
node_auth -->|"upserts users"| node_postgres
node_api_client -.->|"calls API"| node_portfolio_setup
node_portfolio_setup -->|"delegates to"| node_provisioning
node_provisioning -.->|"persists portfolio data"| node_postgres
node_provisioning -.->|"enqueues work"| node_queues
node_worker -->|"consumes jobs"| node_queues
node_worker -->|"creates repositories"| node_github
node_api_client -.->|"uses workspace API"| node_workspace
node_api_client -.->|"submits edits"| node_operations
node_preview_ui -->|"calls preview API"| node_api_client
node_api_client -.->|"sends preview requests"| node_preview_routes
node_preview_routes -->|"delegates to"| node_preview
node_preview -->|"enqueues sandbox jobs"| node_queues
node_preview -->|"reads portfolio data"| node_postgres
node_api_client -.->|"calls publish API"| node_publish
node_publish -->|"uses workspace"| node_workspace
node_worker -->|"deploys portfolios"| node_hosting
node_api_client -.->|"uses copilot API"| node_copilot
node_api_client -.->|"uses catalogue API"| node_catalogue
node_api_client -.->|"uses billing API"| node_billing
node_api_client -.->|"uses admin API"| node_admin_tools
node_api_client -.->|"submits legal requests"| node_legal

click node_admin_web "https://github.com/sumitverma77/plinth-platform/tree/main/admin/app"
click node_api_client "https://github.com/sumitverma77/plinth-platform/blob/main/admin/lib/api.ts"
click node_auth "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/auth/auth.service.ts"
click node_auth_routes "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/auth/auth.controller.ts"
click node_portfolio_setup "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/provisioning/portfolios.controller.ts"
click node_provisioning "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/provisioning/portfolios.service.ts"
click node_workspace "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/workspace/workspace.service.ts"
click node_operations "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/operations/operations.service.ts"
click node_preview_ui "https://github.com/sumitverma77/plinth-platform/blob/main/admin/lib/usePreview.ts"
click node_preview_routes "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/sandbox/preview.controller.ts"
click node_preview "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/sandbox/preview.service.ts"
click node_publish "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/operations/publish.controller.ts"
click node_copilot "https://github.com/sumitverma77/plinth-platform/tree/main/backend/src/copilot"
click node_catalogue "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/catalogue/catalogue.controller.ts"
click node_billing "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/billing/billing.controller.ts"
click node_admin_tools "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/admin/admin.controller.ts"
click node_legal "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/legal/legal.controller.ts"
click node_postgres "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/prisma/prisma.service.ts"
click node_queues "https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/queue/queue.module.ts"
click node_worker "https://github.com/sumitverma77/plinth-platform/tree/main/backend/src"

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_admin_web,node_api_client,node_preview_ui toneBlue
class node_auth,node_auth_routes toneAmber
class node_portfolio_setup,node_provisioning,node_workspace,node_operations,node_preview_routes,node_preview,node_publish,node_copilot toneMint
class node_catalogue,node_billing,node_admin_tools,node_legal,node_worker toneRose
class node_postgres,node_queues,node_user,node_github,node_hosting toneIndigo
```

## Components

### User experience

- [Next.js admin](https://github.com/sumitverma77/plinth-platform/tree/main/admin/app): `admin/app`
- [API client](https://github.com/sumitverma77/plinth-platform/blob/main/admin/lib/api.ts): `admin/lib/api.ts`
- [Preview controls](https://github.com/sumitverma77/plinth-platform/blob/main/admin/lib/usePreview.ts): `admin/lib/usePreview.ts`

### Identity and account

- [Authentication](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [Auth routes](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/auth/auth.controller.ts): `backend/src/auth/auth.controller.ts`

### Portfolio lifecycle

- [Portfolio setup](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/provisioning/portfolios.controller.ts): `backend/src/provisioning/portfolios.controller.ts`
- [Provisioning](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/provisioning/portfolios.service.ts): `backend/src/provisioning/portfolios.service.ts`
- [Workspace editing](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/workspace/workspace.service.ts): `backend/src/workspace/workspace.service.ts`
- [Edit operations](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/operations/operations.service.ts): `backend/src/operations/operations.service.ts`
- [Preview routes](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/sandbox/preview.controller.ts): `backend/src/sandbox/preview.controller.ts`
- [Preview lifecycle](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/sandbox/preview.service.ts): `backend/src/sandbox/preview.service.ts`
- [Publish](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/operations/publish.controller.ts): `backend/src/operations/publish.controller.ts`
- [AI copilot](https://github.com/sumitverma77/plinth-platform/tree/main/backend/src/copilot): `backend/src/copilot`

### Platform services

- [Integration catalogue](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/catalogue/catalogue.controller.ts): `backend/src/catalogue/catalogue.controller.ts`
- [Billing](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/billing/billing.controller.ts): `backend/src/billing/billing.controller.ts`
- [Admin tools](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/admin/admin.controller.ts): `backend/src/admin/admin.controller.ts`
- [Legal requests](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/legal/legal.controller.ts): `backend/src/legal/legal.controller.ts`
- [Background worker](https://github.com/sumitverma77/plinth-platform/tree/main/backend/src): `backend/src`

### Persistence and queues

- [PostgreSQL](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/prisma/prisma.service.ts): `backend/src/prisma/prisma.service.ts`
- [Background queues](https://github.com/sumitverma77/plinth-platform/blob/main/backend/src/queue/queue.module.ts): `backend/src/queue/queue.module.ts`

### Other components

- **Portfolio builder**
- **GitHub**
- **Vercel hosting**

## Connections

- Portfolio builder → Next.js admin: uses (evidence: `README.md`)
- Next.js admin → API client: requests through (evidence: `admin/lib/api.ts`)
- API client → Auth routes: sends HTTP requests (evidence: `admin/lib/api.ts`)
- Auth routes → Authentication: delegates to (evidence: `backend/src/auth/auth.controller.ts`)
- Authentication → PostgreSQL: upserts users (evidence: `backend/src/auth/auth.service.ts`)
- API client → Portfolio setup: calls API
- Portfolio setup → Provisioning: delegates to (evidence: `backend/src/provisioning/portfolios.controller.ts`)
- Provisioning → PostgreSQL: persists portfolio data
- Provisioning → Background queues: enqueues work
- Background worker → Background queues: consumes jobs (evidence: `README.md`)
- Background worker → GitHub: creates repositories (evidence: `README.md`)
- API client → Workspace editing: uses workspace API
- API client → Edit operations: submits edits
- Preview controls → API client: calls preview API (evidence: `admin/lib/usePreview.ts`)
- API client → Preview routes: sends preview requests
- Preview routes → Preview lifecycle: delegates to (evidence: `backend/src/sandbox/preview.controller.ts`)
- Preview lifecycle → Background queues: enqueues sandbox jobs (evidence: `backend/src/sandbox/preview.service.ts`)
- Preview lifecycle → PostgreSQL: reads portfolio data (evidence: `backend/src/sandbox/preview.service.ts`)
- API client → Publish: calls publish API
- Publish → Workspace editing: uses workspace (evidence: `backend/src/operations/publish.controller.ts`)
- Background worker → Vercel hosting: deploys portfolios (evidence: `README.md`)
- API client → AI copilot: uses copilot API
- API client → Integration catalogue: uses catalogue API
- API client → Billing: uses billing API
- API client → Admin tools: uses admin API
- API client → Legal requests: submits legal requests
