# mrtds224/alora architecture

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

- Interactive diagram: https://gitdiagram.com/mrtds224/alora
- Repository: https://github.com/mrtds224/alora

## Overview

ALORA is a collaborative corpus-collection platform for under-resourced African languages. Volunteers or field collectors provide speaker/session details and record prompt-guided speech; the backend stores audio and metadata, analyzes recording quality, supports review and versioned transcription, and exports a speaker-disjoint corpus. The graph includes documented offline capture and acoustic-QA capabilities. Some subsystem paths and links rely on README or source-index references; unsampled implementations are not treated as inspected.

Main entry points: [`app/main.py`](https://github.com/mrtds224/alora/blob/main/app/main.py) (ALORA server), [`app/routers/web.py`](https://github.com/mrtds224/alora/blob/main/app/routers/web.py) (Web pages), [`app/routers/api_public.py`](https://github.com/mrtds224/alora/blob/main/app/routers/api_public.py) (Public API), [`app/services/auth.py`](https://github.com/mrtds224/alora/blob/main/app/services/auth.py) (Authentication and roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Participation and web"]
  node_browser["Capture interface<br/>[contribute.js]"]
  node_recorder["Audio recorder<br/>[recorder.js]"]
  node_offline_queue["Offline queue<br/>[offline_queue.js]"]
  node_web_pages["Web pages<br/>[web.py]"]
  node_api_public["Public API<br/>[api_public.py]"]
end

subgraph group_collection["Corpus collection"]
  node_api_sessions["Session API<br/>[api_sessions.py]"]
  node_api_speakers["Speaker API<br/>[api_speakers.py]"]
  node_api_prompts["Prompt API<br/>[api_prompts.py]"]
  node_api_recordings["Recording API<br/>[api_recordings.py]"]
  node_sessions["Session management<br/>[session.py]"]
  node_speakers["Speaker management<br/>[speaker.py]"]
  node_prompts["Prompt rotation<br/>[prompt.py]"]
  node_recordings["Audio processing<br/>[recording.py]"]
  node_audio_qa["Acoustic QA<br/>[audio_qa.py]"]
end

subgraph group_review["Review and annotation"]
  node_quality["Quality review<br/>[quality.py]"]
  node_api_segmentation["Segmentation API"]
  node_segmentation["Speech segmentation<br/>[segmentation.py]"]
  node_api_transcriptions["Transcription API"]
  node_transcription["Versioned transcription<br/>[transcription.py]"]
  node_api_export["Export API<br/>[api_export.py]"]
  node_export["Corpus export<br/>[export.py]"]
end

subgraph group_platform["Platform services"]
  node_auth["Authentication and roles<br/>[auth.py]"]
  node_storage["Object storage<br/>[storage.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_fastapi["ALORA server<br/>[main.py]"]
end

node_volunteer(("Volunteer"))
node_field_team(("Field and review team"))

node_volunteer -->|"uses"| node_browser
node_field_team -->|"uses"| node_web_pages
node_browser -.->|"records with"| node_recorder
node_browser -->|"queues offline"| node_offline_queue
node_browser -.->|"submits to"| node_api_public
node_web_pages -->|"calls"| node_sessions
node_web_pages -->|"calls"| node_speakers
node_web_pages -->|"calls"| node_prompts
node_web_pages -->|"calls"| node_recordings
node_web_pages -->|"calls"| node_quality
node_web_pages -->|"calls"| node_transcription
node_api_public -->|"selects prompts"| node_prompts
node_api_public -->|"manages sessions"| node_sessions
node_api_public -->|"manages speakers"| node_speakers
node_api_public -->|"submits audio"| node_recordings
node_api_sessions -->|"calls"| node_sessions
node_api_speakers -->|"calls"| node_speakers
node_api_prompts -->|"calls"| node_prompts
node_api_recordings -->|"calls"| node_recordings
node_api_recordings -->|"reviews quality"| node_quality
node_recordings -->|"analyzes audio"| node_audio_qa
node_recordings -->|"stores audio"| node_storage
node_api_segmentation -->|"calls"| node_segmentation
node_api_segmentation -->|"retrieves recordings"| node_recordings
node_api_transcriptions -->|"calls"| node_transcription
node_api_transcriptions -->|"retrieves recordings"| node_recordings
node_api_export -->|"calls"| node_export
node_export -->|"reads audio"| node_storage
node_export -->|"uses segments"| node_segmentation
node_api_public -->|"checks access"| node_auth
node_api_sessions -->|"checks roles"| node_auth
node_api_speakers -->|"checks roles"| node_auth
node_api_prompts -->|"checks roles"| node_auth
node_api_recordings -->|"checks roles"| node_auth
node_api_segmentation -->|"checks roles"| node_auth
node_api_transcriptions -->|"checks roles"| node_auth
node_api_export -->|"checks roles"| node_auth
node_fastapi -->|"registers"| node_api_public
node_fastapi -->|"registers"| node_api_sessions
node_fastapi -->|"registers"| node_api_speakers
node_fastapi -->|"registers"| node_api_prompts
node_fastapi -->|"registers"| node_api_recordings
node_fastapi -->|"registers"| node_api_segmentation
node_fastapi -->|"registers"| node_api_transcriptions
node_fastapi -->|"registers"| node_api_export
node_fastapi -->|"registers"| node_web_pages

click node_browser "https://github.com/mrtds224/alora/blob/main/static/js/contribute.js"
click node_recorder "https://github.com/mrtds224/alora/blob/main/static/js/recorder.js"
click node_offline_queue "https://github.com/mrtds224/alora/blob/main/static/js/offline_queue.js"
click node_web_pages "https://github.com/mrtds224/alora/blob/main/app/routers/web.py"
click node_api_public "https://github.com/mrtds224/alora/blob/main/app/routers/api_public.py"
click node_api_sessions "https://github.com/mrtds224/alora/blob/main/app/routers/api_sessions.py"
click node_api_speakers "https://github.com/mrtds224/alora/blob/main/app/routers/api_speakers.py"
click node_api_prompts "https://github.com/mrtds224/alora/blob/main/app/routers/api_prompts.py"
click node_api_recordings "https://github.com/mrtds224/alora/blob/main/app/routers/api_recordings.py"
click node_sessions "https://github.com/mrtds224/alora/blob/main/app/services/session.py"
click node_speakers "https://github.com/mrtds224/alora/blob/main/app/services/speaker.py"
click node_prompts "https://github.com/mrtds224/alora/blob/main/app/services/prompt.py"
click node_recordings "https://github.com/mrtds224/alora/blob/main/app/services/recording.py"
click node_audio_qa "https://github.com/mrtds224/alora/blob/main/app/services/audio_qa.py"
click node_quality "https://github.com/mrtds224/alora/blob/main/app/services/quality.py"
click node_api_segmentation "https://github.com/mrtds224/alora/blob/main/app/routers/api_segmentation.py"
click node_segmentation "https://github.com/mrtds224/alora/blob/main/app/services/segmentation.py"
click node_api_transcriptions "https://github.com/mrtds224/alora/blob/main/app/routers/api_transcriptions.py"
click node_transcription "https://github.com/mrtds224/alora/blob/main/app/services/transcription.py"
click node_api_export "https://github.com/mrtds224/alora/blob/main/app/routers/api_export.py"
click node_export "https://github.com/mrtds224/alora/blob/main/app/services/export.py"
click node_auth "https://github.com/mrtds224/alora/blob/main/app/services/auth.py"
click node_storage "https://github.com/mrtds224/alora/blob/main/app/services/storage.py"
click node_database "https://github.com/mrtds224/alora/blob/main/app/core/database.py"
click node_fastapi "https://github.com/mrtds224/alora/blob/main/app/main.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_browser,node_recorder,node_offline_queue,node_web_pages,node_api_public,node_field_team toneBlue
class node_api_sessions,node_api_speakers,node_api_prompts,node_api_recordings,node_sessions,node_speakers,node_prompts,node_recordings,node_audio_qa toneAmber
class node_quality,node_api_segmentation,node_segmentation,node_api_transcriptions,node_transcription,node_api_export,node_export toneMint
class node_auth,node_storage,node_database,node_fastapi toneRose
class node_volunteer toneIndigo
```

## Components

### Participation and web

- [Capture interface](https://github.com/mrtds224/alora/blob/main/static/js/contribute.js): `static/js/contribute.js`
- [Audio recorder](https://github.com/mrtds224/alora/blob/main/static/js/recorder.js): `static/js/recorder.js`
- [Offline queue](https://github.com/mrtds224/alora/blob/main/static/js/offline_queue.js): `static/js/offline_queue.js`
- [Web pages](https://github.com/mrtds224/alora/blob/main/app/routers/web.py): `app/routers/web.py`
- [Public API](https://github.com/mrtds224/alora/blob/main/app/routers/api_public.py): `app/routers/api_public.py`

### Corpus collection

- [Session API](https://github.com/mrtds224/alora/blob/main/app/routers/api_sessions.py): `app/routers/api_sessions.py`
- [Speaker API](https://github.com/mrtds224/alora/blob/main/app/routers/api_speakers.py): `app/routers/api_speakers.py`
- [Prompt API](https://github.com/mrtds224/alora/blob/main/app/routers/api_prompts.py): `app/routers/api_prompts.py`
- [Recording API](https://github.com/mrtds224/alora/blob/main/app/routers/api_recordings.py): `app/routers/api_recordings.py`
- [Session management](https://github.com/mrtds224/alora/blob/main/app/services/session.py): `app/services/session.py`
- [Speaker management](https://github.com/mrtds224/alora/blob/main/app/services/speaker.py): `app/services/speaker.py`
- [Prompt rotation](https://github.com/mrtds224/alora/blob/main/app/services/prompt.py): `app/services/prompt.py`
- [Audio processing](https://github.com/mrtds224/alora/blob/main/app/services/recording.py): `app/services/recording.py`
- [Acoustic QA](https://github.com/mrtds224/alora/blob/main/app/services/audio_qa.py): `app/services/audio_qa.py`

### Review and annotation

- [Quality review](https://github.com/mrtds224/alora/blob/main/app/services/quality.py): `app/services/quality.py`
- [Segmentation API](https://github.com/mrtds224/alora/blob/main/app/routers/api_segmentation.py): `app/routers/api_segmentation.py`
- [Speech segmentation](https://github.com/mrtds224/alora/blob/main/app/services/segmentation.py): `app/services/segmentation.py`
- [Transcription API](https://github.com/mrtds224/alora/blob/main/app/routers/api_transcriptions.py): `app/routers/api_transcriptions.py`
- [Versioned transcription](https://github.com/mrtds224/alora/blob/main/app/services/transcription.py): `app/services/transcription.py`
- [Export API](https://github.com/mrtds224/alora/blob/main/app/routers/api_export.py): `app/routers/api_export.py`
- [Corpus export](https://github.com/mrtds224/alora/blob/main/app/services/export.py): `app/services/export.py`

### Platform services

- [Authentication and roles](https://github.com/mrtds224/alora/blob/main/app/services/auth.py): `app/services/auth.py`
- [Object storage](https://github.com/mrtds224/alora/blob/main/app/services/storage.py): `app/services/storage.py`
- [PostgreSQL](https://github.com/mrtds224/alora/blob/main/app/core/database.py): `app/core/database.py`
- [ALORA server](https://github.com/mrtds224/alora/blob/main/app/main.py): `app/main.py`

### Other components

- **Volunteer**
- **Field and review team**

## Connections

- Volunteer → Capture interface: uses
- Field and review team → Web pages: uses
- Capture interface → Audio recorder: records with
- Capture interface → Offline queue: queues offline
- Capture interface → Public API: submits to
- Web pages → Session management: calls (evidence: `app/routers/web.py`)
- Web pages → Speaker management: calls (evidence: `app/routers/web.py`)
- Web pages → Prompt rotation: calls (evidence: `app/routers/web.py`)
- Web pages → Audio processing: calls (evidence: `app/routers/web.py`)
- Web pages → Quality review: calls (evidence: `app/routers/web.py`)
- Web pages → Versioned transcription: calls (evidence: `app/routers/web.py`)
- Public API → Prompt rotation: selects prompts (evidence: `app/routers/api_public.py`)
- Public API → Session management: manages sessions (evidence: `app/routers/api_public.py`)
- Public API → Speaker management: manages speakers (evidence: `app/routers/api_public.py`)
- Public API → Audio processing: submits audio (evidence: `app/routers/api_public.py`)
- Session API → Session management: calls (evidence: `app/routers/api_sessions.py`)
- Speaker API → Speaker management: calls (evidence: `app/routers/api_speakers.py`)
- Prompt API → Prompt rotation: calls (evidence: `app/routers/api_prompts.py`)
- Recording API → Audio processing: calls (evidence: `app/routers/api_recordings.py`)
- Recording API → Quality review: reviews quality (evidence: `app/routers/api_recordings.py`)
- Audio processing → Acoustic QA: analyzes audio (evidence: `app/services/recording.py`)
- Audio processing → Object storage: stores audio (evidence: `app/services/recording.py`)
- Segmentation API → Speech segmentation: calls (evidence: `app/routers/api_segmentation.py`)
- Segmentation API → Audio processing: retrieves recordings (evidence: `app/routers/api_segmentation.py`)
- Transcription API → Versioned transcription: calls (evidence: `app/routers/api_transcriptions.py`)
- Transcription API → Audio processing: retrieves recordings (evidence: `app/routers/api_transcriptions.py`)
- Export API → Corpus export: calls (evidence: `app/routers/api_export.py`)
- Corpus export → Object storage: reads audio (evidence: `app/services/export.py`)
- Corpus export → Speech segmentation: uses segments (evidence: `app/services/export.py`)
- Public API → Authentication and roles: checks access (evidence: `app/routers/api_public.py`)
- Session API → Authentication and roles: checks roles (evidence: `app/routers/api_sessions.py`)
- Speaker API → Authentication and roles: checks roles (evidence: `app/routers/api_speakers.py`)
- Prompt API → Authentication and roles: checks roles (evidence: `app/routers/api_prompts.py`)
- Recording API → Authentication and roles: checks roles (evidence: `app/routers/api_recordings.py`)
- Segmentation API → Authentication and roles: checks roles (evidence: `app/routers/api_segmentation.py`)
- Transcription API → Authentication and roles: checks roles (evidence: `app/routers/api_transcriptions.py`)
- Export API → Authentication and roles: checks roles (evidence: `app/routers/api_export.py`)
- ALORA server → Public API: registers (evidence: `app/main.py`)
- ALORA server → Session API: registers (evidence: `app/main.py`)
- ALORA server → Speaker API: registers (evidence: `app/main.py`)
- ALORA server → Prompt API: registers (evidence: `app/main.py`)
- ALORA server → Recording API: registers (evidence: `app/main.py`)
- ALORA server → Segmentation API: registers (evidence: `app/main.py`)
- ALORA server → Transcription API: registers (evidence: `app/main.py`)
- ALORA server → Export API: registers (evidence: `app/main.py`)
- ALORA server → Web pages: registers (evidence: `app/main.py`)
