# hyacinth18-creator/sauti-ai-ke architecture

> Architecture diagram of the GitHub repository hyacinth18-creator/sauti-ai-ke, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyacinth18-creator/sauti-ai-ke
- Repository: https://github.com/hyacinth18-creator/sauti-ai-ke

## Overview

SAUTI-AI-KE is a community-incident reporting app. Residents speak a report, receive transcription and follow-up support, and submit an analyzed incident for a reference number; they can also view reports and look up an incident. Account sign-in and voice-service session support are separate capabilities. The README documents incident status history and updates in Supabase. Some page logic and subsystems are unsampled, so links not established by the excerpts are omitted.

Main entry points: [`src/app/page.tsx`](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/page.tsx) (Reporting interface), [`src/app/api/incidents/route.ts`](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/incidents/route.ts) (Incident collection API), [`supabase/migrations/20260904000000_create_incidents.sql`](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql) (Incident records), [`src/app/api/voice/transcribe/route.ts`](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/transcribe/route.ts) (Transcription endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reporting["Voice reporting"]
  node_home["Reporting interface<br/>[page.tsx]"]
  node_transcription["Transcription endpoint<br/>[route.ts]"]
  node_followup["Follow-up endpoint<br/>[route.ts]"]
  node_session["Voice session endpoint<br/>[route.ts]"]
  node_health["Service health endpoint<br/>[route.ts]"]
end

subgraph group_incidents["Incident workflow"]
  node_analysis["Incident analysis"]
  node_validation["Incident validation"]
  node_collection["Incident collection API<br/>[route.ts]"]
  node_lookup["Reference lookup API<br/>[route.ts]"]
  node_incidentservice["Incident operations<br/>[incidents.ts]"]
  node_serverclient["Server database client<br/>[supabase-server.ts]"]
  node_incidentdb[("Incident records")]
  node_history[("Status history")]
  node_updates[("Incident updates")]
end

subgraph group_identity["Accounts"]
  node_authpanel["Account panel<br/>[auth-panel.tsx]"]
  node_browserclient["Browser auth client"]
  node_callback["OAuth callback<br/>[route.ts]"]
end

subgraph group_services["External services"]
  node_supabaseauth{{"Supabase Auth"}}
  node_assemblyai{{"AssemblyAI"}}
end

node_resident(("Resident"))

node_resident -->|"speaks report"| node_home
node_home -->|"uploads audio"| node_transcription
node_transcription -->|"uploads and polls"| node_assemblyai
node_assemblyai -->|"returns transcript"| node_transcription
node_home -->|"requests question"| node_followup
node_followup -->|"generates question"| node_assemblyai
node_home -->|"analyzes transcript"| node_analysis
node_home -->|"submits report"| node_collection
node_collection -->|"validates input"| node_validation
node_collection -->|"creates or lists"| node_incidentservice
node_incidentservice -->|"queries database"| node_serverclient
node_serverclient -->|"reads and writes"| node_incidentdb
node_incidentdb -->|"records status changes"| node_history
node_incidentdb -->|"stores updates"| node_updates
node_home -->|"looks up reference"| node_lookup
node_lookup -->|"finds incident"| node_incidentservice
node_home -->|"shows account controls"| node_authpanel
node_home -->|"checks signed-in user"| node_browserclient
node_authpanel -->|"manages account"| node_browserclient
node_browserclient -->|"authenticates"| node_supabaseauth
node_callback -->|"exchanges code"| node_supabaseauth
node_session -->|"requests session token"| node_assemblyai
node_health -->|"checks connectivity"| node_assemblyai

click node_home "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/page.tsx"
click node_transcription "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/transcribe/route.ts"
click node_followup "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/follow-up/route.ts"
click node_session "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/session/route.ts"
click node_health "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/assemblyai/health/route.ts"
click node_analysis "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incident-analysis.ts"
click node_validation "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incident-validation.ts"
click node_collection "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/incidents/route.ts"
click node_lookup "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/incidents/%5Breference%5D/route.ts"
click node_incidentservice "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incidents.ts"
click node_serverclient "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/supabase-server.ts"
click node_incidentdb "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql"
click node_history "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql"
click node_updates "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql"
click node_authpanel "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/auth-panel.tsx"
click node_browserclient "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/supabase-browser.ts"
click node_callback "https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/auth/callback/route.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_home,node_transcription,node_followup,node_session,node_health toneBlue
class node_analysis,node_validation,node_collection,node_lookup,node_incidentservice,node_serverclient,node_incidentdb,node_history,node_updates toneAmber
class node_authpanel,node_browserclient,node_callback toneMint
class node_supabaseauth,node_assemblyai toneRose
class node_resident toneIndigo
```

## Components

### Voice reporting

- [Reporting interface](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Transcription endpoint](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/transcribe/route.ts): `src/app/api/voice/transcribe/route.ts`
- [Follow-up endpoint](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/follow-up/route.ts): `src/app/api/voice/follow-up/route.ts`
- [Voice session endpoint](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/voice/session/route.ts): `src/app/api/voice/session/route.ts`
- [Service health endpoint](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/assemblyai/health/route.ts): `src/app/api/assemblyai/health/route.ts`

### Incident workflow

- [Incident analysis](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incident-analysis.ts): `src/lib/incident-analysis.ts`
- [Incident validation](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incident-validation.ts): `src/lib/incident-validation.ts`
- [Incident collection API](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/incidents/route.ts): `src/app/api/incidents/route.ts`
- [Reference lookup API](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/api/incidents/%5Breference%5D/route.ts): `src/app/api/incidents/[reference]/route.ts`
- [Incident operations](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/incidents.ts): `src/lib/incidents.ts`
- [Server database client](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/supabase-server.ts): `src/lib/supabase-server.ts`
- [Incident records](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql): `supabase/migrations/20260904000000_create_incidents.sql`
- [Status history](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql): `supabase/migrations/20260904000000_create_incidents.sql`
- [Incident updates](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/supabase/migrations/20260904000000_create_incidents.sql): `supabase/migrations/20260904000000_create_incidents.sql`

### Accounts

- [Account panel](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/auth-panel.tsx): `src/app/auth-panel.tsx`
- [Browser auth client](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/lib/supabase-browser.ts): `src/lib/supabase-browser.ts`
- [OAuth callback](https://github.com/hyacinth18-creator/sauti-ai-ke/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`

### External services

- **Supabase Auth**
- **AssemblyAI**

### Other components

- **Resident**

## Connections

- Resident → Reporting interface: speaks report
- Reporting interface → Transcription endpoint: uploads audio
- Transcription endpoint → AssemblyAI: uploads and polls
- AssemblyAI → Transcription endpoint: returns transcript
- Reporting interface → Follow-up endpoint: requests question
- Follow-up endpoint → AssemblyAI: generates question
- Reporting interface → Incident analysis: analyzes transcript
- Reporting interface → Incident collection API: submits report
- Incident collection API → Incident validation: validates input
- Incident collection API → Incident operations: creates or lists
- Incident operations → Server database client: queries database
- Server database client → Incident records: reads and writes
- Incident records → Status history: records status changes
- Incident records → Incident updates: stores updates
- Reporting interface → Reference lookup API: looks up reference
- Reference lookup API → Incident operations: finds incident
- Reporting interface → Account panel: shows account controls
- Reporting interface → Browser auth client: checks signed-in user
- Account panel → Browser auth client: manages account
- Browser auth client → Supabase Auth: authenticates
- OAuth callback → Supabase Auth: exchanges code
- Voice session endpoint → AssemblyAI: requests session token
- Service health endpoint → AssemblyAI: checks connectivity