# satishreddysr777/fynvic-api architecture

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

- Interactive diagram: https://gitdiagram.com/satishreddysr777/fynvic-api
- Repository: https://github.com/satishreddysr777/fynvic-api

## Overview

Fynvic API is the HTTP backend and gateway for an AI mock-interview platform. A candidate authenticates, creates and runs an interview session, submits voice or coding activity, then receives asynchronously scored results and can share a report. The API owns session lifecycle, billing, LiveKit integration, discovery, media, operations, audit, and persistence; assessment materialization and scoring are companion services accessed over authenticated HTTP. The graph reflects documented boundaries and excerpted calls; some major subsystems are represented at module level because their implementation was not sampled.

Main entry points: [`src/db/client.ts`](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/client.ts) (Postgres), [`src/app/server.ts`](https://github.com/satishreddysr777/fynvic-api/blob/main/src/app/server.ts) (HTTP API), [`src/modules/sessions/routes.ts`](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/routes.ts) (Session routes), [`src/clients/assessment.client.ts`](https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/assessment.client.ts) (Assessment client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API runtime"]
  node_api["HTTP API<br/>[server.ts]"]
  node_routing["Route registry<br/>[router.ts]"]
end

subgraph group_identity["Identity and commerce"]
  node_auth_routes["Authentication<br/>[routes.ts]"]
  node_auth_guard["Auth guard<br/>[auth.ts]"]
  node_user_repo["User repository"]
  node_billing["Billing<br/>[routes.ts]"]
  node_payment_provider["Dodo payments<br/>[dodo-provider.ts]"]
end

subgraph group_interview["Interview experience"]
  node_sessions["Session routes<br/>[routes.ts]"]
  node_session_services["Session lifecycle"]
  node_livekit["Voice rooms<br/>[routes.ts]"]
  node_coding["Coding interviews<br/>[coding.routes.ts]"]
  node_sharing["Share reports<br/>[share.routes.ts]"]
end

subgraph group_services["Companion services"]
  node_assessment["Assessment service"]
  node_assessment_client["Assessment client"]
  node_scoring["Scoring service"]
  node_scoring_client["Scoring client<br/>[scoring.client.ts]"]
  node_internal_scoring["Scoring callbacks"]
  node_service_request["Service HTTP<br/>[service-request.ts]"]
end

subgraph group_platform["Data and operations"]
  node_discovery["Candidate discovery"]
  node_ops["Operations tools<br/>[routes.ts]"]
  node_retention["Retention jobs<br/>[reaper.ts]"]
  node_database[("Postgres<br/>[client.ts]")]
  node_schema_auth["Auth schema<br/>[auth.ts]"]
  node_schema_billing["Billing schema<br/>[billing.ts]"]
  node_schema_sessions["Session schema<br/>[sessions.ts]"]
  node_schema_assessments["Assessment schema<br/>[assessments.ts]"]
  node_schema_audit["Audit schema<br/>[audit.ts]"]
  node_schema_enums["Shared enums<br/>[enums.ts]"]
end

node_candidate(("Candidate"))
node_business(("Business user"))
node_voice_agent(("Voice agent"))

node_candidate -->|"uses HTTP"| node_api
node_business -->|"uses HTTP"| node_api
node_voice_agent -->|"calls callbacks"| node_api
node_api -->|"mounts routes"| node_routing
node_api -->|"mounts"| node_auth_routes
node_api -->|"mounts"| node_billing
node_api -->|"mounts"| node_sessions
node_api -->|"mounts"| node_livekit
node_auth_routes -->|"guards access"| node_auth_guard
node_auth_guard -->|"checks account"| node_user_repo
node_billing -->|"guards checkout"| node_auth_guard
node_billing -.->|"initiates payment"| node_payment_provider
node_sessions -->|"handles lifecycle"| node_session_services
node_sessions -.->|"lists blueprints"| node_assessment_client
node_sessions -->|"streams recording"| node_livekit
node_candidate -->|"starts interview"| node_sessions
node_voice_agent -->|"posts events"| node_sessions
node_candidate -->|"submits code"| node_coding
node_candidate -->|"shares report"| node_sharing
node_session_services -->|"reads session data"| node_database
node_assessment_client -->|"uses HTTP"| node_service_request
node_scoring_client -->|"uses HTTP"| node_service_request
node_assessment_client -->|"requests materialization"| node_assessment
node_ops -->|"proxies authoring"| node_assessment_client
node_scoring_client -->|"requests scoring"| node_scoring
node_scoring -->|"posts results"| node_internal_scoring
node_internal_scoring -.->|"persists results"| node_database
node_discovery -.->|"queries candidates"| node_database
node_retention -.->|"purges retained data"| node_database
node_database -->|"uses schema"| node_schema_auth
node_database -->|"uses schema"| node_schema_billing
node_database -->|"uses schema"| node_schema_sessions
node_database -->|"uses schema"| node_schema_assessments
node_database -->|"uses schema"| node_schema_audit
node_database -->|"uses schema"| node_schema_enums

click node_api "https://github.com/satishreddysr777/fynvic-api/blob/main/src/app/server.ts"
click node_routing "https://github.com/satishreddysr777/fynvic-api/blob/main/src/lib/router.ts"
click node_auth_routes "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/auth/routes.ts"
click node_auth_guard "https://github.com/satishreddysr777/fynvic-api/blob/main/src/middleware/auth.ts"
click node_user_repo "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/auth/services/repository/users.repository.ts"
click node_billing "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/billing/routes.ts"
click node_payment_provider "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/billing/payments/dodo-provider.ts"
click node_sessions "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/routes.ts"
click node_session_services "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/services/sessions.service.ts"
click node_livekit "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/livekit/routes.ts"
click node_coding "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/coding.routes.ts"
click node_sharing "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/share.routes.ts"
click node_assessment_client "https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/assessment.client.ts"
click node_scoring_client "https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/scoring.client.ts"
click node_internal_scoring "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/internal/scoring-persist.service.ts"
click node_discovery "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/discovery/discovery.service.ts"
click node_ops "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/ops/routes.ts"
click node_retention "https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/retention/reaper.ts"
click node_database "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/client.ts"
click node_schema_auth "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/auth.ts"
click node_schema_billing "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/billing.ts"
click node_schema_sessions "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/sessions.ts"
click node_schema_assessments "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/assessments.ts"
click node_schema_audit "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/audit.ts"
click node_schema_enums "https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/enums.ts"
click node_service_request "https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/service-request.ts"

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_api,node_routing,node_business toneBlue
class node_auth_routes,node_auth_guard,node_user_repo,node_billing,node_payment_provider toneAmber
class node_sessions,node_session_services,node_livekit,node_coding,node_sharing toneMint
class node_assessment,node_assessment_client,node_scoring,node_scoring_client,node_internal_scoring,node_service_request toneRose
class node_discovery,node_ops,node_retention,node_database,node_schema_auth,node_schema_billing,node_schema_sessions,node_schema_assessments,node_schema_audit,node_schema_enums,node_candidate,node_voice_agent toneIndigo
```

## Components

### API runtime

- [HTTP API](https://github.com/satishreddysr777/fynvic-api/blob/main/src/app/server.ts): `src/app/server.ts`
- [Route registry](https://github.com/satishreddysr777/fynvic-api/blob/main/src/lib/router.ts): `src/lib/router.ts`

### Identity and commerce

- [Authentication](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/auth/routes.ts): `src/modules/auth/routes.ts`
- [Auth guard](https://github.com/satishreddysr777/fynvic-api/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [User repository](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/auth/services/repository/users.repository.ts): `src/modules/auth/services/repository/users.repository.ts`
- [Billing](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/billing/routes.ts): `src/modules/billing/routes.ts`
- [Dodo payments](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/billing/payments/dodo-provider.ts): `src/modules/billing/payments/dodo-provider.ts`

### Interview experience

- [Session routes](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/routes.ts): `src/modules/sessions/routes.ts`
- [Session lifecycle](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/services/sessions.service.ts): `src/modules/sessions/services/sessions.service.ts`
- [Voice rooms](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/livekit/routes.ts): `src/modules/livekit/routes.ts`
- [Coding interviews](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/coding.routes.ts): `src/modules/sessions/coding.routes.ts`
- [Share reports](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/sessions/share.routes.ts): `src/modules/sessions/share.routes.ts`

### Companion services

- **Assessment service**
- [Assessment client](https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/assessment.client.ts): `src/clients/assessment.client.ts`
- **Scoring service**
- [Scoring client](https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/scoring.client.ts): `src/clients/scoring.client.ts`
- [Scoring callbacks](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/internal/scoring-persist.service.ts): `src/modules/internal/scoring-persist.service.ts`
- [Service HTTP](https://github.com/satishreddysr777/fynvic-api/blob/main/src/clients/service-request.ts): `src/clients/service-request.ts`

### Data and operations

- [Candidate discovery](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/discovery/discovery.service.ts): `src/modules/discovery/discovery.service.ts`
- [Operations tools](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/ops/routes.ts): `src/modules/ops/routes.ts`
- [Retention jobs](https://github.com/satishreddysr777/fynvic-api/blob/main/src/modules/retention/reaper.ts): `src/modules/retention/reaper.ts`
- [Postgres](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/client.ts): `src/db/client.ts`
- [Auth schema](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/auth.ts): `src/db/schema/auth.ts`
- [Billing schema](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/billing.ts): `src/db/schema/billing.ts`
- [Session schema](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/sessions.ts): `src/db/schema/sessions.ts`
- [Assessment schema](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/assessments.ts): `src/db/schema/assessments.ts`
- [Audit schema](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/audit.ts): `src/db/schema/audit.ts`
- [Shared enums](https://github.com/satishreddysr777/fynvic-api/blob/main/src/db/schema/enums.ts): `src/db/schema/enums.ts`

### Other components

- **Candidate**
- **Business user**
- **Voice agent**

## Connections

- Candidate → HTTP API: uses HTTP (evidence: `README.md`)
- Business user → HTTP API: uses HTTP (evidence: `README.md`)
- Voice agent → HTTP API: calls callbacks (evidence: `README.md`)
- HTTP API → Route registry: mounts routes (evidence: `src/app/server.ts`)
- HTTP API → Authentication: mounts (evidence: `src/app/server.ts`)
- HTTP API → Billing: mounts (evidence: `src/app/server.ts`)
- HTTP API → Session routes: mounts (evidence: `src/app/server.ts`)
- HTTP API → Voice rooms: mounts (evidence: `src/app/server.ts`)
- Authentication → Auth guard: guards access
- Auth guard → User repository: checks account (evidence: `src/middleware/auth.ts`)
- Billing → Auth guard: guards checkout (evidence: `src/modules/billing/routes.ts`)
- Billing → Dodo payments: initiates payment
- Session routes → Session lifecycle: handles lifecycle (evidence: `src/modules/sessions/routes.ts`)
- Session routes → Assessment client: lists blueprints
- Session routes → Voice rooms: streams recording (evidence: `src/modules/sessions/routes.ts`)
- Candidate → Session routes: starts interview (evidence: `README.md`)
- Voice agent → Session routes: posts events (evidence: `README.md`)
- Candidate → Coding interviews: submits code (evidence: `README.md`)
- Candidate → Share reports: shares report (evidence: `README.md`)
- Session lifecycle → Postgres: reads session data (evidence: `src/modules/sessions/services/sessions.service.ts`)
- Assessment client → Service HTTP: uses HTTP (evidence: `src/clients/assessment.client.ts`)
- Scoring client → Service HTTP: uses HTTP (evidence: `src/clients/scoring.client.ts`)
- Assessment client → Assessment service: requests materialization (evidence: `README.md`)
- Operations tools → Assessment client: proxies authoring (evidence: `src/modules/ops/routes.ts`)
- Scoring client → Scoring service: requests scoring (evidence: `README.md`)
- Scoring service → Scoring callbacks: posts results (evidence: `README.md`)
- Scoring callbacks → Postgres: persists results
- Candidate discovery → Postgres: queries candidates
- Retention jobs → Postgres: purges retained data
- Postgres → Auth schema: uses schema (evidence: `src/db/client.ts`)
- Postgres → Billing schema: uses schema (evidence: `src/db/client.ts`)
- Postgres → Session schema: uses schema (evidence: `src/db/client.ts`)
- Postgres → Assessment schema: uses schema (evidence: `src/db/client.ts`)
- Postgres → Audit schema: uses schema (evidence: `src/db/client.ts`)
- Postgres → Shared enums: uses schema (evidence: `src/db/client.ts`)
