# chuloo/mural architecture

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

- Interactive diagram: https://gitdiagram.com/chuloo/mural
- Repository: https://github.com/chuloo/mural

## Overview

Mural is a native iOS and Android language-learning app centered on adaptive voice and written conversation. Learners choose languages, practise in themed conversations, use optional meaning support, and build local vocabulary records from conversation evidence. The repository also contains a hosted API with account, voice-session, and minute-commerce capabilities; the README excerpt describes the clients more fully than those hosted features. Edges reflect README statements and source-index references; unshown client-to-hosted-service wiring is left unverified.

Main entry points: [`services/api/src/app.ts`](https://github.com/chuloo/mural/blob/main/services/api/src/app.ts) (HTTP routes), [`services/api/src/auth.ts`](https://github.com/chuloo/mural/blob/main/services/api/src/auth.ts) (Authentication), [`apps/ios/App/ConversationCoordinator.swift`](https://github.com/chuloo/mural/blob/main/apps/ios/App/ConversationCoordinator.swift) (Conversation coordination), [`services/api/src/hosted-voice.ts`](https://github.com/chuloo/mural/blob/main/services/api/src/hosted-voice.ts) (Hosted sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Mobile clients"]
  node_ios["iPhone app<br/>[RootView.swift]"]
  node_android["Android app<br/>[MainActivity.kt]"]
  node_client_api["Network clients<br/>[APIClient.swift]"]
end

subgraph group_learning["Conversation learning"]
  node_talk["Talk interface<br/>[TalkScreen.kt]"]
  node_voice["Voice session"]
  node_conversation["Conversation coordination"]
  node_teaching["Teaching and pacing"]
  node_languages["Language modules"]
  node_meaning["Meaning support"]
  node_learning_engine["Learning records"]
  node_local_store[("Local records<br/>[Storage.swift]")]
end

subgraph group_hosted["Hosted voice"]
  node_service_entry["Service startup<br/>[main.ts]"]
  node_router["HTTP routes<br/>[app.ts]"]
  node_hosted_voice["Hosted sessions<br/>[hosted-voice.ts]"]
  node_provider["Live provider<br/>[live-provider.ts]"]
end

subgraph group_accounts["Accounts and commerce"]
  node_identity["Authentication<br/>[auth.ts]"]
  node_admission["Account admission<br/>[auth-admission.ts]"]
  node_minutes["Minute balances<br/>[minutes.ts]"]
  node_ledger["Credit ledger<br/>[ledger.ts]"]
  node_purchases["Web purchases<br/>[web-purchases.ts]"]
end

subgraph group_storage["Service persistence"]
  node_database[("PostgreSQL<br/>[db.ts]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_ios
node_learner -->|"uses"| node_android
node_ios -->|"practises with"| node_conversation
node_android -->|"opens"| node_talk
node_talk -->|"supports voice"| node_voice
node_conversation -->|"adapts challenge"| node_teaching
node_conversation -->|"uses language"| node_languages
node_conversation -->|"offers meanings"| node_meaning
node_learning_engine -->|"persists learning"| node_local_store
node_learner -->|"builds vocabulary"| node_learning_engine
node_ios -.->|"requests services"| node_client_api
node_android -.->|"requests services"| node_client_api
node_service_entry -->|"starts routes"| node_router
node_router -->|"routes sessions"| node_hosted_voice
node_hosted_voice -->|"parses context"| node_provider
node_service_entry -->|"loads auth"| node_identity
node_router -->|"authenticates"| node_identity
node_identity -->|"locks wallet"| node_ledger
node_identity -->|"funds welcome"| node_minutes
node_hosted_voice -->|"reserves credit"| node_ledger
node_hosted_voice -->|"reserves minutes"| node_minutes
node_router -.->|"checks admission"| node_admission
node_router -->|"serves purchase routes"| node_purchases
node_identity -->|"queries"| node_database
node_ledger -->|"transacts"| node_database
node_minutes -->|"transacts"| node_database
node_purchases -->|"queries"| node_database

click node_ios "https://github.com/chuloo/mural/blob/main/apps/ios/App/RootView.swift"
click node_android "https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/MainActivity.kt"
click node_talk "https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/ui/TalkScreen.kt"
click node_voice "https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/VoiceConversationService.kt"
click node_conversation "https://github.com/chuloo/mural/blob/main/apps/ios/App/ConversationCoordinator.swift"
click node_teaching "https://github.com/chuloo/mural/blob/main/apps/ios/Core/TeachingPolicy.swift"
click node_languages "https://github.com/chuloo/mural/blob/main/apps/ios/Core/Languages/LanguageModule.swift"
click node_meaning "https://github.com/chuloo/mural/blob/main/apps/ios/Core/MeaningController.swift"
click node_learning_engine "https://github.com/chuloo/mural/blob/main/apps/ios/Core/LearningEngine.swift"
click node_local_store "https://github.com/chuloo/mural/blob/main/apps/ios/App/Storage.swift"
click node_client_api "https://github.com/chuloo/mural/blob/main/apps/ios/App/APIClient.swift"
click node_service_entry "https://github.com/chuloo/mural/blob/main/services/api/src/main.ts"
click node_router "https://github.com/chuloo/mural/blob/main/services/api/src/app.ts"
click node_hosted_voice "https://github.com/chuloo/mural/blob/main/services/api/src/hosted-voice.ts"
click node_provider "https://github.com/chuloo/mural/blob/main/services/api/src/live-provider.ts"
click node_identity "https://github.com/chuloo/mural/blob/main/services/api/src/auth.ts"
click node_admission "https://github.com/chuloo/mural/blob/main/services/api/src/auth-admission.ts"
click node_minutes "https://github.com/chuloo/mural/blob/main/services/api/src/minutes.ts"
click node_ledger "https://github.com/chuloo/mural/blob/main/services/api/src/ledger.ts"
click node_purchases "https://github.com/chuloo/mural/blob/main/services/api/src/web-purchases.ts"
click node_database "https://github.com/chuloo/mural/blob/main/services/api/src/db.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_ios,node_android,node_client_api toneBlue
class node_talk,node_voice,node_conversation,node_teaching,node_languages,node_meaning,node_learning_engine,node_local_store toneAmber
class node_service_entry,node_router,node_hosted_voice,node_provider toneMint
class node_identity,node_admission,node_minutes,node_ledger,node_purchases toneRose
class node_database,node_learner toneIndigo
```

## Components

### Mobile clients

- [iPhone app](https://github.com/chuloo/mural/blob/main/apps/ios/App/RootView.swift): `apps/ios/App/RootView.swift`
- [Android app](https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/MainActivity.kt): `apps/android/app/src/main/java/chat/mural/MainActivity.kt`
- [Network clients](https://github.com/chuloo/mural/blob/main/apps/ios/App/APIClient.swift): `apps/ios/App/APIClient.swift`

### Conversation learning

- [Talk interface](https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/ui/TalkScreen.kt): `apps/android/app/src/main/java/chat/mural/ui/TalkScreen.kt`
- [Voice session](https://github.com/chuloo/mural/blob/main/apps/android/app/src/main/java/chat/mural/VoiceConversationService.kt): `apps/android/app/src/main/java/chat/mural/VoiceConversationService.kt`
- [Conversation coordination](https://github.com/chuloo/mural/blob/main/apps/ios/App/ConversationCoordinator.swift): `apps/ios/App/ConversationCoordinator.swift`
- [Teaching and pacing](https://github.com/chuloo/mural/blob/main/apps/ios/Core/TeachingPolicy.swift): `apps/ios/Core/TeachingPolicy.swift`
- [Language modules](https://github.com/chuloo/mural/blob/main/apps/ios/Core/Languages/LanguageModule.swift): `apps/ios/Core/Languages/LanguageModule.swift`
- [Meaning support](https://github.com/chuloo/mural/blob/main/apps/ios/Core/MeaningController.swift): `apps/ios/Core/MeaningController.swift`
- [Learning records](https://github.com/chuloo/mural/blob/main/apps/ios/Core/LearningEngine.swift): `apps/ios/Core/LearningEngine.swift`
- [Local records](https://github.com/chuloo/mural/blob/main/apps/ios/App/Storage.swift): `apps/ios/App/Storage.swift`

### Hosted voice

- [Service startup](https://github.com/chuloo/mural/blob/main/services/api/src/main.ts): `services/api/src/main.ts`
- [HTTP routes](https://github.com/chuloo/mural/blob/main/services/api/src/app.ts): `services/api/src/app.ts`
- [Hosted sessions](https://github.com/chuloo/mural/blob/main/services/api/src/hosted-voice.ts): `services/api/src/hosted-voice.ts`
- [Live provider](https://github.com/chuloo/mural/blob/main/services/api/src/live-provider.ts): `services/api/src/live-provider.ts`

### Accounts and commerce

- [Authentication](https://github.com/chuloo/mural/blob/main/services/api/src/auth.ts): `services/api/src/auth.ts`
- [Account admission](https://github.com/chuloo/mural/blob/main/services/api/src/auth-admission.ts): `services/api/src/auth-admission.ts`
- [Minute balances](https://github.com/chuloo/mural/blob/main/services/api/src/minutes.ts): `services/api/src/minutes.ts`
- [Credit ledger](https://github.com/chuloo/mural/blob/main/services/api/src/ledger.ts): `services/api/src/ledger.ts`
- [Web purchases](https://github.com/chuloo/mural/blob/main/services/api/src/web-purchases.ts): `services/api/src/web-purchases.ts`

### Service persistence

- [PostgreSQL](https://github.com/chuloo/mural/blob/main/services/api/src/db.ts): `services/api/src/db.ts`

### Other components

- **Learner**

## Connections

- Learner → iPhone app: uses (evidence: `README.md`)
- Learner → Android app: uses (evidence: `README.md`)
- iPhone app → Conversation coordination: practises with (evidence: `README.md`)
- Android app → Talk interface: opens (evidence: `README.md`)
- Talk interface → Voice session: supports voice (evidence: `README.md`)
- Conversation coordination → Teaching and pacing: adapts challenge (evidence: `README.md`)
- Conversation coordination → Language modules: uses language (evidence: `apps/ios/Core/Languages/LanguageModule.swift`)
- Conversation coordination → Meaning support: offers meanings (evidence: `README.md`)
- Learning records → Local records: persists learning (evidence: `apps/ios/App/Storage.swift`)
- Learner → Learning records: builds vocabulary (evidence: `README.md`)
- iPhone app → Network clients: requests services
- Android app → Network clients: requests services
- Service startup → HTTP routes: starts routes (evidence: `services/api/src/main.ts`)
- HTTP routes → Hosted sessions: routes sessions (evidence: `services/api/src/app.ts`)
- Hosted sessions → Live provider: parses context (evidence: `services/api/src/hosted-voice.ts`)
- Service startup → Authentication: loads auth (evidence: `services/api/src/main.ts`)
- HTTP routes → Authentication: authenticates (evidence: `services/api/src/app.ts`)
- Authentication → Credit ledger: locks wallet (evidence: `services/api/src/auth.ts`)
- Authentication → Minute balances: funds welcome (evidence: `services/api/src/auth.ts`)
- Hosted sessions → Credit ledger: reserves credit (evidence: `services/api/src/hosted-voice.ts`)
- Hosted sessions → Minute balances: reserves minutes (evidence: `services/api/src/hosted-voice.ts`)
- HTTP routes → Account admission: checks admission (evidence: `services/api/src/app.ts`)
- HTTP routes → Web purchases: serves purchase routes (evidence: `services/api/src/app.ts`)
- Authentication → PostgreSQL: queries (evidence: `services/api/src/auth.ts`)
- Credit ledger → PostgreSQL: transacts (evidence: `services/api/src/ledger.ts`)
- Minute balances → PostgreSQL: transacts (evidence: `services/api/src/minutes.ts`)
- Web purchases → PostgreSQL: queries (evidence: `services/api/src/web-purchases.ts`)
