# mulla759/speakez architecture

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

- Interactive diagram: https://gitdiagram.com/mulla759/speakez
- Repository: https://github.com/mulla759/speakez

## Overview

SpeakEz is a location-based anonymous voice-note app. A user records at a campus place; the app uploads the note, a queued worker transcribes and titles it, and the safety gate determines whether it can proceed to publication. Nearby listeners discover notes on the map, request a server-side distance unlock, and hear audio with a synchronized transcript; they can reply or react. The app also supports private journals, drafts, daily prompts, saved notes, and OTP sign-in. The graph follows documented capabilities; some unsampled wiring is represented only at its documented subsystem boundary.

Main entry points: [`src/api.ts`](https://github.com/mulla759/speakez/blob/main/src/api.ts) (API client), [`api/app/db.py`](https://github.com/mulla759/speakez/blob/main/api/app/db.py) (Postgres and PostGIS), [`worker/pipeline.py`](https://github.com/mulla759/speakez/blob/main/worker/pipeline.py) (Transcription worker), [`api/app/main.py`](https://github.com/mulla759/speakez/blob/main/api/app/main.py) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_map["Map discovery<br/>[MapScreen.tsx]"]
  node_record["Record and review<br/>[record.tsx]"]
  node_story["Story playback<br/>[&#91;id&#93;.tsx]"]
  node_journal["Journal and prompts<br/>[journal.tsx]"]
  node_saved["Saved notes<br/>[saved.tsx]"]
  node_profile["Profile and sign-in<br/>[profile.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_session["Session management<br/>[session.ts]"]
end

subgraph group_api["API and services"]
  node_apiapp["HTTP application<br/>[main.py]"]
  node_note_routes["Note endpoints<br/>[notes.py]"]
  node_landmark_routes["Map endpoints<br/>[landmarks.py]"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_reaction_routes["Reaction endpoints<br/>[reactions.py]"]
  node_notes_service["Note and unlock rules<br/>[notes.py]"]
  node_auth_service["Account auth<br/>[auth.py]"]
  node_queue["Job queue<br/>[queue.py]"]
end

subgraph group_pipeline["Processing and publication"]
  node_worker["Transcription worker<br/>[pipeline.py]"]
  node_safety["Safety review<br/>[safety.py]"]
  node_publisher["Scheduled publishing<br/>[publish.py]"]
end

subgraph group_state["Data and media"]
  node_database[("Postgres and PostGIS<br/>[db.py]")]
  node_cache[("Redis cache<br/>[cache.py]")]
  node_media[("Audio storage<br/>[storage.py]")]
end

node_person(("Campus user"))
node_email["Email delivery"]

node_person -->|"explores"| node_map
node_person -->|"records"| node_record
node_person -->|"reviews privately"| node_journal
node_person -->|"listens nearby"| node_story
node_person -->|"signs in"| node_profile
node_map -->|"fetches map"| node_client
node_record -->|"submits audio"| node_client
node_story -->|"requests unlock"| node_client
node_story -->|"saves reaction"| node_client
node_journal -->|"loads journal"| node_client
node_saved -->|"loads saved"| node_client
node_profile -->|"manages session"| node_session
node_session -->|"sends OTP requests"| node_auth_routes
node_client -->|"sends requests"| node_apiapp
node_apiapp -->|"dispatches notes"| node_note_routes
node_apiapp -->|"dispatches map"| node_landmark_routes
node_apiapp -->|"dispatches auth"| node_auth_routes
node_apiapp -->|"dispatches reactions"| node_reaction_routes
node_note_routes -->|"applies note rules"| node_notes_service
node_note_routes -->|"enqueues processing"| node_queue
node_landmark_routes -->|"queries landmarks"| node_database
node_landmark_routes -->|"caches map"| node_cache
node_notes_service -->|"checks and stores notes"| node_database
node_notes_service -->|"issues audio access"| node_media
node_worker -->|"consumes jobs"| node_queue
node_worker -->|"reads audio"| node_media
node_worker -->|"loads and updates notes"| node_database
node_worker -->|"checks transcript"| node_safety
node_safety -->|"records verdict"| node_database
node_publisher -->|"releases due notes"| node_database
node_worker -.->|"schedules release"| node_publisher
node_auth_routes -->|"verifies account"| node_auth_service
node_auth_service -->|"loads account"| node_database
node_auth_routes -.->|"sends OTP"| node_email
node_reaction_routes -->|"stores reactions"| node_database

click node_map "https://github.com/mulla759/speakez/blob/main/src/MapScreen.tsx"
click node_record "https://github.com/mulla759/speakez/blob/main/app/record.tsx"
click node_story "https://github.com/mulla759/speakez/blob/main/app/story/%5Bid%5D.tsx"
click node_journal "https://github.com/mulla759/speakez/blob/main/app/journal.tsx"
click node_saved "https://github.com/mulla759/speakez/blob/main/app/saved.tsx"
click node_profile "https://github.com/mulla759/speakez/blob/main/app/profile.tsx"
click node_client "https://github.com/mulla759/speakez/blob/main/src/api.ts"
click node_session "https://github.com/mulla759/speakez/blob/main/src/session.ts"
click node_apiapp "https://github.com/mulla759/speakez/blob/main/api/app/main.py"
click node_note_routes "https://github.com/mulla759/speakez/blob/main/api/app/routes/notes.py"
click node_landmark_routes "https://github.com/mulla759/speakez/blob/main/api/app/routes/landmarks.py"
click node_auth_routes "https://github.com/mulla759/speakez/blob/main/api/app/routes/auth.py"
click node_reaction_routes "https://github.com/mulla759/speakez/blob/main/api/app/routes/reactions.py"
click node_notes_service "https://github.com/mulla759/speakez/blob/main/api/app/services/notes.py"
click node_auth_service "https://github.com/mulla759/speakez/blob/main/api/app/services/auth.py"
click node_queue "https://github.com/mulla759/speakez/blob/main/api/app/queue.py"
click node_worker "https://github.com/mulla759/speakez/blob/main/worker/pipeline.py"
click node_safety "https://github.com/mulla759/speakez/blob/main/api/app/services/safety.py"
click node_publisher "https://github.com/mulla759/speakez/blob/main/api/app/services/publish.py"
click node_database "https://github.com/mulla759/speakez/blob/main/api/app/db.py"
click node_cache "https://github.com/mulla759/speakez/blob/main/api/app/cache.py"
click node_media "https://github.com/mulla759/speakez/blob/main/api/app/storage.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_map,node_record,node_story,node_journal,node_saved,node_profile,node_client,node_session,node_person toneBlue
class node_apiapp,node_note_routes,node_landmark_routes,node_auth_routes,node_reaction_routes,node_notes_service,node_auth_service,node_queue toneAmber
class node_worker,node_safety,node_publisher toneMint
class node_database,node_cache,node_media toneRose
class node_email toneIndigo
```

## Components

### Mobile app

- [Map discovery](https://github.com/mulla759/speakez/blob/main/src/MapScreen.tsx): `src/MapScreen.tsx`
- [Record and review](https://github.com/mulla759/speakez/blob/main/app/record.tsx): `app/record.tsx`
- [Story playback](https://github.com/mulla759/speakez/blob/main/app/story/%5Bid%5D.tsx): `app/story/[id].tsx`
- [Journal and prompts](https://github.com/mulla759/speakez/blob/main/app/journal.tsx): `app/journal.tsx`
- [Saved notes](https://github.com/mulla759/speakez/blob/main/app/saved.tsx): `app/saved.tsx`
- [Profile and sign-in](https://github.com/mulla759/speakez/blob/main/app/profile.tsx): `app/profile.tsx`
- [API client](https://github.com/mulla759/speakez/blob/main/src/api.ts): `src/api.ts`
- [Session management](https://github.com/mulla759/speakez/blob/main/src/session.ts): `src/session.ts`

### API and services

- [HTTP application](https://github.com/mulla759/speakez/blob/main/api/app/main.py): `api/app/main.py`
- [Note endpoints](https://github.com/mulla759/speakez/blob/main/api/app/routes/notes.py): `api/app/routes/notes.py`
- [Map endpoints](https://github.com/mulla759/speakez/blob/main/api/app/routes/landmarks.py): `api/app/routes/landmarks.py`
- [Auth endpoints](https://github.com/mulla759/speakez/blob/main/api/app/routes/auth.py): `api/app/routes/auth.py`
- [Reaction endpoints](https://github.com/mulla759/speakez/blob/main/api/app/routes/reactions.py): `api/app/routes/reactions.py`
- [Note and unlock rules](https://github.com/mulla759/speakez/blob/main/api/app/services/notes.py): `api/app/services/notes.py`
- [Account auth](https://github.com/mulla759/speakez/blob/main/api/app/services/auth.py): `api/app/services/auth.py`
- [Job queue](https://github.com/mulla759/speakez/blob/main/api/app/queue.py): `api/app/queue.py`

### Processing and publication

- [Transcription worker](https://github.com/mulla759/speakez/blob/main/worker/pipeline.py): `worker/pipeline.py`
- [Safety review](https://github.com/mulla759/speakez/blob/main/api/app/services/safety.py): `api/app/services/safety.py`
- [Scheduled publishing](https://github.com/mulla759/speakez/blob/main/api/app/services/publish.py): `api/app/services/publish.py`

### Data and media

- [Postgres and PostGIS](https://github.com/mulla759/speakez/blob/main/api/app/db.py): `api/app/db.py`
- [Redis cache](https://github.com/mulla759/speakez/blob/main/api/app/cache.py): `api/app/cache.py`
- [Audio storage](https://github.com/mulla759/speakez/blob/main/api/app/storage.py): `api/app/storage.py`

### Other components

- **Campus user**
- **Email delivery**

## Connections

- Campus user → Map discovery: explores
- Campus user → Record and review: records
- Campus user → Journal and prompts: reviews privately
- Campus user → Story playback: listens nearby
- Campus user → Profile and sign-in: signs in
- Map discovery → API client: fetches map
- Record and review → API client: submits audio
- Story playback → API client: requests unlock
- Story playback → API client: saves reaction
- Journal and prompts → API client: loads journal
- Saved notes → API client: loads saved
- Profile and sign-in → Session management: manages session
- Session management → Auth endpoints: sends OTP requests
- API client → HTTP application: sends requests
- HTTP application → Note endpoints: dispatches notes
- HTTP application → Map endpoints: dispatches map
- HTTP application → Auth endpoints: dispatches auth
- HTTP application → Reaction endpoints: dispatches reactions
- Note endpoints → Note and unlock rules: applies note rules
- Note endpoints → Job queue: enqueues processing
- Map endpoints → Postgres and PostGIS: queries landmarks
- Map endpoints → Redis cache: caches map
- Note and unlock rules → Postgres and PostGIS: checks and stores notes
- Note and unlock rules → Audio storage: issues audio access
- Transcription worker → Job queue: consumes jobs
- Transcription worker → Audio storage: reads audio
- Transcription worker → Postgres and PostGIS: loads and updates notes
- Transcription worker → Safety review: checks transcript
- Safety review → Postgres and PostGIS: records verdict
- Scheduled publishing → Postgres and PostGIS: releases due notes
- Transcription worker → Scheduled publishing: schedules release
- Auth endpoints → Account auth: verifies account
- Account auth → Postgres and PostGIS: loads account
- Auth endpoints → Email delivery: sends OTP
- Reaction endpoints → Postgres and PostGIS: stores reactions