# pjungjs/consultly architecture

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

- Interactive diagram: https://gitdiagram.com/pjungjs/consultly
- Repository: https://github.com/pjungjs/consultly

## Overview

Consultly is a two-sided consultant-booking product: clients discover consultants, choose local-time slots, check out, and manage bookings; consultants maintain profiles and availability and manage sessions. The NestJS API owns booking, payment, identity, brief, and support rules, backed by PostgreSQL and external services. The AI service extracts PDF text and generates prep sheets or help replies. The graph combines sampled calls and explicit README architecture; unsampled features are included at their supported directory paths, with only documented or indexed relationships shown.

Main entry points: [`web/lib/api.ts`](https://github.com/pjungjs/consultly/blob/main/web/lib/api.ts) (API client), [`ai/src/ai/main.py`](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/main.py) (AI HTTP service), [`api/src/orders/orders.service.ts`](https://github.com/pjungjs/consultly/blob/main/api/src/orders/orders.service.ts) (Orders and booking rules), [`api/src/prisma/prisma.service.ts`](https://github.com/pjungjs/consultly/blob/main/api/src/prisma/prisma.service.ts) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Client and consultant web"]
  node_webapp["Web experience<br/>[page.tsx]"]
  node_discovery["Consultant discovery<br/>[page.tsx]"]
  node_slotpicker["Slot selection<br/>[slot-picker.tsx]"]
  node_bookingsui["Bookings and checkout<br/>[my-bookings.tsx]"]
  node_dashboard["Consultant dashboard"]
  node_briefui["Brief and prep sheet UI<br/>[brief-view.tsx]"]
  node_helpui["Help assistant UI<br/>[support-chat.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["Booking API"]
  node_consultants["Consultant catalog and availability"]
  node_profiles["Profiles and availability settings"]
  node_orders["Orders and booking rules<br/>[orders.service.ts]"]
  node_auth["Passwordless identity and demos<br/>[auth.service.ts]"]
  node_briefs["Brief management"]
  node_support["Help gateway and AI budget"]
  node_webhook["Payment webhook"]
end

subgraph group_data["Persistence and integrations"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
  node_stripe["Stripe Checkout and refunds<br/>[stripe.service.ts]"]
  node_email["Email delivery<br/>[email.service.ts]"]
  node_storage["Brief file storage<br/>[brief-files.ts]"]
end

subgraph group_ai["AI services"]
  node_aiservice["AI HTTP service<br/>[main.py]"]
  node_pdf["PDF text extraction<br/>[pdf.py]"]
  node_prepsheet["Prep sheet generation<br/>[prep_sheet.py]"]
  node_helpagent["Help topics and replies<br/>[support.py]"]
  node_topics["Help topic content<br/>[help_topics.py]"]
end

node_visitor(("Client or consultant"))
node_claude{{"Claude API"}}
node_resend{{"Email provider"}}

node_visitor -->|"uses"| node_webapp
node_webapp -->|"browses"| node_discovery
node_discovery -->|"loads listings"| node_webapi
node_discovery -->|"opens consultant"| node_slotpicker
node_slotpicker -.->|"requests slots"| node_webapi
node_slotpicker -.->|"starts booking"| node_bookingsui
node_bookingsui -.->|"manages bookings"| node_webapi
node_dashboard -.->|"manages sessions"| node_webapi
node_briefui -.->|"loads brief"| node_webapi
node_helpui -.->|"sends messages"| node_webapi
node_webapi -.->|"API requests"| node_consultants
node_webapi -.->|"API requests"| node_orders
node_webapi -.->|"API requests"| node_auth
node_webapi -.->|"API requests"| node_briefs
node_webapi -.->|"API requests"| node_support
node_profiles -->|"reads and writes"| node_database
node_auth -->|"stores identity"| node_database
node_auth -->|"sends sign-in link"| node_email
node_consultants -.->|"reads catalog"| node_database
node_orders -->|"persists orders"| node_database
node_orders -->|"creates checkout and refunds"| node_stripe
node_orders -->|"sends booking notices"| node_email
node_webhook -->|"verifies event"| node_stripe
node_webhook -->|"confirms payment"| node_orders
node_briefs -.->|"manages PDF files"| node_storage
node_briefs -.->|"requests prep sheet"| node_aiservice
node_support -->|"forwards chat"| node_aiservice
node_aiservice -->|"extracts PDF text"| node_pdf
node_aiservice -->|"writes summary"| node_prepsheet
node_aiservice -->|"handles support chat"| node_helpagent
node_helpagent -->|"uses topics"| node_topics
node_prepsheet -.->|"generates with"| node_claude
node_helpagent -.->|"answers with"| node_claude
node_aiservice -.->|"looks up user bookings"| node_orders
node_email -.->|"delivers mail"| node_resend

click node_webapp "https://github.com/pjungjs/consultly/blob/main/web/app/page.tsx"
click node_discovery "https://github.com/pjungjs/consultly/blob/main/web/app/consultants/page.tsx"
click node_slotpicker "https://github.com/pjungjs/consultly/blob/main/web/app/consultants/%5Bid%5D/slot-picker.tsx"
click node_bookingsui "https://github.com/pjungjs/consultly/blob/main/web/app/my-bookings/my-bookings.tsx"
click node_dashboard "https://github.com/pjungjs/consultly/blob/main/web/app/dashboard/consultant-dashboard.tsx"
click node_briefui "https://github.com/pjungjs/consultly/blob/main/web/app/brief-view.tsx"
click node_helpui "https://github.com/pjungjs/consultly/blob/main/web/app/support-chat.tsx"
click node_webapi "https://github.com/pjungjs/consultly/blob/main/web/lib/api.ts"
click node_consultants "https://github.com/pjungjs/consultly/blob/main/api/src/consultants/consultants.service.ts"
click node_profiles "https://github.com/pjungjs/consultly/blob/main/api/src/auth/profile.controller.ts"
click node_orders "https://github.com/pjungjs/consultly/blob/main/api/src/orders/orders.service.ts"
click node_auth "https://github.com/pjungjs/consultly/blob/main/api/src/auth/auth.service.ts"
click node_briefs "https://github.com/pjungjs/consultly/blob/main/api/src/briefs/briefs.controller.ts"
click node_support "https://github.com/pjungjs/consultly/blob/main/api/src/support/support.controller.ts"
click node_database "https://github.com/pjungjs/consultly/blob/main/api/src/prisma/prisma.service.ts"
click node_stripe "https://github.com/pjungjs/consultly/blob/main/api/src/stripe/stripe.service.ts"
click node_webhook "https://github.com/pjungjs/consultly/blob/main/api/src/stripe/stripe-webhook.controller.ts"
click node_email "https://github.com/pjungjs/consultly/blob/main/api/src/email/email.service.ts"
click node_storage "https://github.com/pjungjs/consultly/blob/main/api/src/briefs/brief-files.ts"
click node_aiservice "https://github.com/pjungjs/consultly/blob/main/ai/src/ai/main.py"
click node_pdf "https://github.com/pjungjs/consultly/blob/main/ai/src/ai/pdf.py"
click node_prepsheet "https://github.com/pjungjs/consultly/blob/main/ai/src/ai/prep_sheet.py"
click node_helpagent "https://github.com/pjungjs/consultly/blob/main/ai/src/ai/support.py"
click node_topics "https://github.com/pjungjs/consultly/blob/main/ai/src/ai/help_topics.py"

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_webapp,node_discovery,node_slotpicker,node_bookingsui,node_dashboard,node_briefui,node_helpui,node_webapi,node_visitor toneBlue
class node_consultants,node_profiles,node_orders,node_auth,node_briefs,node_support,node_webhook toneAmber
class node_database,node_stripe,node_email,node_storage,node_claude toneMint
class node_aiservice,node_pdf,node_prepsheet,node_helpagent,node_topics toneRose
class node_resend toneIndigo
```

## Components

### Client and consultant web

- [Web experience](https://github.com/pjungjs/consultly/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Consultant discovery](https://github.com/pjungjs/consultly/blob/main/web/app/consultants/page.tsx): `web/app/consultants/page.tsx`
- [Slot selection](https://github.com/pjungjs/consultly/blob/main/web/app/consultants/%5Bid%5D/slot-picker.tsx): `web/app/consultants/[id]/slot-picker.tsx`
- [Bookings and checkout](https://github.com/pjungjs/consultly/blob/main/web/app/my-bookings/my-bookings.tsx): `web/app/my-bookings/my-bookings.tsx`
- [Consultant dashboard](https://github.com/pjungjs/consultly/blob/main/web/app/dashboard/consultant-dashboard.tsx): `web/app/dashboard/consultant-dashboard.tsx`
- [Brief and prep sheet UI](https://github.com/pjungjs/consultly/blob/main/web/app/brief-view.tsx): `web/app/brief-view.tsx`
- [Help assistant UI](https://github.com/pjungjs/consultly/blob/main/web/app/support-chat.tsx): `web/app/support-chat.tsx`
- [API client](https://github.com/pjungjs/consultly/blob/main/web/lib/api.ts): `web/lib/api.ts`

### Booking API

- [Consultant catalog and availability](https://github.com/pjungjs/consultly/blob/main/api/src/consultants/consultants.service.ts): `api/src/consultants/consultants.service.ts`
- [Profiles and availability settings](https://github.com/pjungjs/consultly/blob/main/api/src/auth/profile.controller.ts): `api/src/auth/profile.controller.ts`
- [Orders and booking rules](https://github.com/pjungjs/consultly/blob/main/api/src/orders/orders.service.ts): `api/src/orders/orders.service.ts`
- [Passwordless identity and demos](https://github.com/pjungjs/consultly/blob/main/api/src/auth/auth.service.ts): `api/src/auth/auth.service.ts`
- [Brief management](https://github.com/pjungjs/consultly/blob/main/api/src/briefs/briefs.controller.ts): `api/src/briefs/briefs.controller.ts`
- [Help gateway and AI budget](https://github.com/pjungjs/consultly/blob/main/api/src/support/support.controller.ts): `api/src/support/support.controller.ts`
- [Payment webhook](https://github.com/pjungjs/consultly/blob/main/api/src/stripe/stripe-webhook.controller.ts): `api/src/stripe/stripe-webhook.controller.ts`

### Persistence and integrations

- [PostgreSQL](https://github.com/pjungjs/consultly/blob/main/api/src/prisma/prisma.service.ts): `api/src/prisma/prisma.service.ts`
- [Stripe Checkout and refunds](https://github.com/pjungjs/consultly/blob/main/api/src/stripe/stripe.service.ts): `api/src/stripe/stripe.service.ts`
- [Email delivery](https://github.com/pjungjs/consultly/blob/main/api/src/email/email.service.ts): `api/src/email/email.service.ts`
- [Brief file storage](https://github.com/pjungjs/consultly/blob/main/api/src/briefs/brief-files.ts): `api/src/briefs/brief-files.ts`

### AI services

- [AI HTTP service](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/main.py): `ai/src/ai/main.py`
- [PDF text extraction](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/pdf.py): `ai/src/ai/pdf.py`
- [Prep sheet generation](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/prep_sheet.py): `ai/src/ai/prep_sheet.py`
- [Help topics and replies](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/support.py): `ai/src/ai/support.py`
- [Help topic content](https://github.com/pjungjs/consultly/blob/main/ai/src/ai/help_topics.py): `ai/src/ai/help_topics.py`

### Other components

- **Client or consultant**
- **Claude API**
- **Email provider**

## Connections

- Client or consultant → Web experience: uses (evidence: `README.md`)
- Web experience → Consultant discovery: browses (evidence: `web/app/page.tsx`)
- Consultant discovery → API client: loads listings (evidence: `web/app/consultants/page.tsx`)
- Consultant discovery → Slot selection: opens consultant
- Slot selection → API client: requests slots
- Slot selection → Bookings and checkout: starts booking
- Bookings and checkout → API client: manages bookings
- Consultant dashboard → API client: manages sessions
- Brief and prep sheet UI → API client: loads brief
- Help assistant UI → API client: sends messages
- API client → Consultant catalog and availability: API requests (evidence: `README.md`)
- API client → Orders and booking rules: API requests (evidence: `README.md`)
- API client → Passwordless identity and demos: API requests (evidence: `README.md`)
- API client → Brief management: API requests (evidence: `README.md`)
- API client → Help gateway and AI budget: API requests (evidence: `README.md`)
- Profiles and availability settings → PostgreSQL: reads and writes (evidence: `api/src/auth/profile.controller.ts`)
- Passwordless identity and demos → PostgreSQL: stores identity (evidence: `api/src/auth/auth.service.ts`)
- Passwordless identity and demos → Email delivery: sends sign-in link (evidence: `api/src/auth/auth.service.ts`)
- Consultant catalog and availability → PostgreSQL: reads catalog
- Orders and booking rules → PostgreSQL: persists orders (evidence: `api/src/orders/orders.service.ts`)
- Orders and booking rules → Stripe Checkout and refunds: creates checkout and refunds (evidence: `api/src/orders/orders.service.ts`)
- Orders and booking rules → Email delivery: sends booking notices (evidence: `api/src/orders/orders.service.ts`)
- Payment webhook → Stripe Checkout and refunds: verifies event (evidence: `api/src/stripe/stripe-webhook.controller.ts`)
- Payment webhook → Orders and booking rules: confirms payment (evidence: `api/src/stripe/stripe-webhook.controller.ts`)
- Brief management → Brief file storage: manages PDF files (evidence: `api/src/briefs/briefs.controller.ts`)
- Brief management → AI HTTP service: requests prep sheet (evidence: `README.md`)
- Help gateway and AI budget → AI HTTP service: forwards chat (evidence: `api/src/support/support.controller.ts`)
- AI HTTP service → PDF text extraction: extracts PDF text (evidence: `ai/src/ai/main.py`)
- AI HTTP service → Prep sheet generation: writes summary (evidence: `ai/src/ai/main.py`)
- AI HTTP service → Help topics and replies: handles support chat (evidence: `ai/src/ai/main.py`)
- Help topics and replies → Help topic content: uses topics (evidence: `ai/src/ai/support.py`)
- Prep sheet generation → Claude API: generates with (evidence: `README.md`)
- Help topics and replies → Claude API: answers with (evidence: `README.md`)
- AI HTTP service → Orders and booking rules: looks up user bookings (evidence: `README.md`)
- Email delivery → Email provider: delivers mail (evidence: `README.md`)