# ivanslavinskyi/callassist architecture

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

- Interactive diagram: https://gitdiagram.com/ivanslavinskyi/callassist
- Repository: https://github.com/ivanslavinskyi/callassist

## Overview

SHPROHLI is a multilingual call-assistance application: people prepare and approve a plan, conduct a supported phone conversation, then review saved transcript and optional AI results. The web app initiates user and admin actions through the API; API services coordinate preparation, call execution, persistence, and result delivery. Separate branches cover authentication, credits, safety review, public content, and operational telemetry. Some subsystem links rely on README capability descriptions because their source was not sampled; these are cited to the README rather than presented as inspected call sites.

Main entry points: [`apps/api/src/call-service.ts`](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/call-service.ts) (Call orchestration), [`apps/api/src/app.ts`](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/app.ts) (HTTP API), [`apps/web/components/admin-calls-console.tsx`](https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/admin-calls-console.tsx) (Admin console), [`apps/web/components/create-call-form.tsx`](https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/create-call-form.tsx) (User web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_web["User web app"]
  node_adminweb["Admin console"]
end

subgraph group_api["API workflows"]
  node_api["HTTP API<br/>[app.ts]"]
  node_auth["Accounts and auth<br/>[auth-service.ts]"]
  node_content["Localized content<br/>[content-service.ts]"]
  node_brief["Plan compilation<br/>[brief-compiler.ts]"]
  node_calls["Call orchestration<br/>[call-service.ts]"]
end

subgraph group_voice["Call execution"]
  node_voice["Live voice session"]
  node_telephony["Phone provider"]
  node_transcript["Transcript capture"]
end

subgraph group_data["Persistence and results"]
  node_text["AI text results"]
  node_store[("Call records")]
  node_credits["Credit accounting<br/>[credit-service.ts]"]
  node_notifications["Result notifications"]
end

subgraph group_operations["Administration and operations"]
  node_safety["Safety review"]
  node_telemetry["Telemetry exports<br/>[service.ts]"]
  node_beta["Beta controls<br/>[beta-controls.ts]"]
end

node_person(("Caller"))

node_person -->|"uses"| node_web
node_web -->|"requests"| node_api
node_adminweb -->|"admin requests"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"serves content"| node_content
node_api -->|"compiles plans"| node_brief
node_api -->|"routes calls"| node_calls
node_calls -->|"runs session"| node_voice
node_calls -->|"places calls"| node_telephony
node_voice -->|"captures transcript"| node_transcript
node_calls -->|"persists call"| node_store
node_calls -->|"accounts usage"| node_credits
node_calls -->|"creates results"| node_text
node_text -.->|"saves artifacts"| node_store
node_calls -->|"sends result email"| node_notifications
node_adminweb -->|"reviews plans"| node_safety
node_adminweb -->|"requests exports"| node_telemetry
node_api -->|"applies controls"| node_beta
node_beta -->|"manages allowances"| node_credits

click node_web "https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/create-call-form.tsx"
click node_adminweb "https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/admin-calls-console.tsx"
click node_api "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/auth/auth-service.ts"
click node_content "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/content/content-service.ts"
click node_brief "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/brief-compiler/brief-compiler.ts"
click node_calls "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/call-service.ts"
click node_voice "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/voice/unified-live-call.ts"
click node_telephony "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/telephony/telephony-provider.ts"
click node_transcript "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/storage/native-transcript.ts"
click node_text "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/text-processing/text-artifact-service.ts"
click node_store "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/storage/postgres-call-repository.ts"
click node_credits "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/credits/credit-service.ts"
click node_notifications "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/notifications/user-call-notifications.ts"
click node_safety "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/safety/plan-review-service.ts"
click node_telemetry "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/telemetry-export/service.ts"
click node_beta "https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/beta/beta-controls.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_web,node_adminweb toneBlue
class node_api,node_auth,node_content,node_brief,node_calls toneAmber
class node_voice,node_telephony,node_transcript toneMint
class node_text,node_store,node_credits,node_notifications toneRose
class node_safety,node_telemetry,node_beta,node_person toneIndigo
```

## Components

### Web experience

- [User web app](https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/create-call-form.tsx): `apps/web/components/create-call-form.tsx`
- [Admin console](https://github.com/ivanslavinskyi/callassist/blob/main/apps/web/components/admin-calls-console.tsx): `apps/web/components/admin-calls-console.tsx`

### API workflows

- [HTTP API](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Accounts and auth](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/auth/auth-service.ts): `apps/api/src/auth/auth-service.ts`
- [Localized content](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/content/content-service.ts): `apps/api/src/content/content-service.ts`
- [Plan compilation](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/brief-compiler/brief-compiler.ts): `apps/api/src/brief-compiler/brief-compiler.ts`
- [Call orchestration](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/call-service.ts): `apps/api/src/call-service.ts`

### Call execution

- [Live voice session](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/voice/unified-live-call.ts): `apps/api/src/voice/unified-live-call.ts`
- [Phone provider](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/telephony/telephony-provider.ts): `apps/api/src/telephony/telephony-provider.ts`
- [Transcript capture](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/storage/native-transcript.ts): `apps/api/src/storage/native-transcript.ts`

### Persistence and results

- [AI text results](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/text-processing/text-artifact-service.ts): `apps/api/src/text-processing/text-artifact-service.ts`
- [Call records](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/storage/postgres-call-repository.ts): `apps/api/src/storage/postgres-call-repository.ts`
- [Credit accounting](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/credits/credit-service.ts): `apps/api/src/credits/credit-service.ts`
- [Result notifications](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/notifications/user-call-notifications.ts): `apps/api/src/notifications/user-call-notifications.ts`

### Administration and operations

- [Safety review](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/safety/plan-review-service.ts): `apps/api/src/safety/plan-review-service.ts`
- [Telemetry exports](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/telemetry-export/service.ts): `apps/api/src/telemetry-export/service.ts`
- [Beta controls](https://github.com/ivanslavinskyi/callassist/blob/main/apps/api/src/beta/beta-controls.ts): `apps/api/src/beta/beta-controls.ts`

### Other components

- **Caller**

## Connections

- Caller → User web app: uses (evidence: `README.md`)
- User web app → HTTP API: requests (evidence: `README.md`)
- Admin console → HTTP API: admin requests (evidence: `README.md`)
- HTTP API → Accounts and auth: authenticates (evidence: `apps/api/src/app.ts`)
- HTTP API → Localized content: serves content (evidence: `apps/api/src/app.ts`)
- HTTP API → Plan compilation: compiles plans
- HTTP API → Call orchestration: routes calls (evidence: `apps/api/src/app.ts`)
- Call orchestration → Live voice session: runs session (evidence: `README.md`)
- Call orchestration → Phone provider: places calls (evidence: `apps/api/src/call-service.ts`)
- Live voice session → Transcript capture: captures transcript (evidence: `README.md`)
- Call orchestration → Call records: persists call (evidence: `apps/api/src/call-service.ts`)
- Call orchestration → Credit accounting: accounts usage (evidence: `README.md`)
- Call orchestration → AI text results: creates results (evidence: `README.md`)
- AI text results → Call records: saves artifacts
- Call orchestration → Result notifications: sends result email (evidence: `README.md`)
- Admin console → Safety review: reviews plans
- Admin console → Telemetry exports: requests exports
- HTTP API → Beta controls: applies controls (evidence: `apps/api/src/app.ts`)
- Beta controls → Credit accounting: manages allowances (evidence: `apps/api/src/beta/beta-controls.ts`)
