# lvin15/voxsight architecture

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

- Interactive diagram: https://gitdiagram.com/lvin15/voxsight
- Repository: https://github.com/lvin15/voxsight

## Overview

1. **Repository shape**
   - This is a two-part system: an **Android mobile client** under `mobile/` and a **Python backend** under `backend/`.
   - The repo currently shows a **front-end-heavy Android app skeleton** plus a **backend setup placeholder**; the backend’s actual API code is not present in the tree.

2. **Primary user-facing subsystem: Android app**
   - The mobile app is the main delivered product. Its package is `com.cit.kaido.voxsight`.
   - Core entry points are `MainActivity.kt`, `FirstFragment.kt`, and `SecondFragment.kt`, which indicates a **fragment-based UI** rather than a single-screen app.
   - `nav_graph.xml` suggests navigation is managed with the **Android Navigation Component**.

3. **UI composition and boundaries**
   - The Android UI is split across `activity_main.xml`, `content_main.xml`, `fragment_first.xml`, and `fragment_second.xml`.
   - This implies a clear boundary between:
     - the **activity shell** (`MainActivity`) that hosts navigation,
     - and **screen-level fragments** that render individual views.
   - The project uses resource-driven UI definitions in `res/`, which keeps layout, text, theme, and device-specific configuration separate from Kotlin code.

4. **Mobile app runtime and platform concerns**
   - The app is a standard **Android/Kotlin** project using Gradle Kotlin DSL (`build.gradle.kts`).
   - `AndroidManifest.xml` includes `android.permission.INTERNET`, which is important because the app is intended to talk to a remote backend.
   - The presence of multiple `values-*` folders shows the app is prepared for **responsive layouts and theme variants** across screen sizes and night mode.

5. **Client-side networking architecture**
   - The README explicitly lists `Retrofit`, `Gson`, and Kotlin `coroutines`, so the mobile app is intended to use:
     - **Retrofit** for HTTP calls,
     - **Gson** for JSON serialization/deserialization,
     - **coroutines** for asynchronous API work.
   - This strongly suggests the app will fetch or submit data to the backend over a REST-style API, even though the actual API service classes are not visible in the tree.

6. **Backend subsystem**
   - The backend folder currently contains only `requirements.txt`, but the README says it is being set up for **FastAPI**.
   - Architecturally, this means the backend is intended to be a **Python API server** that exposes endpoints consumed by the Android client.
   - Because no backend modules/routes/models are present, the server-side boundaries are not yet implemented in this repository snapshot.

7. **Data flow between client and server**
   - The intended flow is:
     1. user interacts with the Android fragments,
     2. the app calls a backend API over the network,
     3. backend returns JSON,
     4. Retrofit/Gson maps the response into Kotlin-side data models,
     5. UI updates in the fragments.
   - The main architectural boundary is therefore **mobile presentation layer vs. remote API service**.

8. **Domain framing**
   - The README says VoxSight is for “independent sight-reading practice for amateur choir members.”
   - So the app’s domain is **practice support for choir sight-reading**, not a generic utility app.
   - Any future data models and API endpoints will likely revolve around practice content, exercises, user progress, or feedback, though those are not yet visible in code.

9. **Testing boundaries**
   - The mobile app includes both:
     - `src/test` for local unit tests,
     - `src/androidTest` for instrumented Android tests.
   - This indicates the client is expected to have both JVM-level logic tests and device/emulator UI/integration tests.
   - No backend tests are shown in the file tree.

10. **Build and dependency management**
   - The Android project uses the Gradle wrapper and version catalog (`gradle/libs.versions.toml`), which centralizes dependency versions.
   - The backend appears to rely on a Python virtual environment and `backend/requirements.txt`.
   - So the repo has **two separate dependency ecosystems**: Gradle/Kotlin for the app and pip/FastAPI for the server.

11. **What to diagram as the key architectural boxes**
   - Box 1: **Android app UI** (`MainActivity`, `FirstFragment`, `SecondFragment`, layouts, nav graph)
   - Box 2: **Android networking layer** (Retrofit/Gson/coroutines, implied but not yet implemented in the tree)
   - Box 3: **FastAPI backend** (planned server boundary, currently only dependency setup)
   - Box 4: **Android resources and configuration** (`res/`, manifest, themes, permissions)
   - Box 5: **Tests** (`test/`, `androidTest/`)

12. **Current maturity**
   - The repository is in an **early integration stage**: the Android shell is present, the backend is planned, and the networking stack has been chosen.
   - For an architecture diagram, it is important to show the backend as an external or upcoming service boundary rather than a fully realized subsystem in this snapshot.

Main entry points: [`mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt`](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt) (MainActivity), [`mobile/app/build.gradle.kts`](https://github.com/lvin15/voxsight/blob/main/mobile/app/build.gradle.kts) (App build), [`mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt`](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt) (First screen), [`mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt`](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt) (Second screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Android app"]
  node_main_activity["MainActivity<br/>activity shell<br/>[MainActivity.kt]"]
  node_first_fragment["First screen<br/>fragment<br/>[FirstFragment.kt]"]
  node_second_fragment["Second screen<br/>fragment<br/>[SecondFragment.kt]"]
  node_nav_graph["Nav graph<br/>navigation<br/>[nav_graph.xml]"]
  node_activity_layout["Activity layout<br/>[activity_main.xml]"]
  node_content_layout["Content layout<br/>[content_main.xml]"]
  node_first_layout["First layout<br/>[fragment_first.xml]"]
  node_second_layout["Second layout"]
  node_resources[("Resources<br/>res bundle")]
  node_manifest["Manifest"]
  node_network_stack["Network stack<br/>client networking"]
end

subgraph group_backend["Python backend"]
  node_remote_api["Remote API<br/>backend service"]
  node_backend_setup["Backend setup<br/>python deps<br/>[requirements.txt]"]
end

subgraph group_build["Build setup"]
  node_app_build["App build<br/>gradle build<br/>[build.gradle.kts]"]
  node_versions["Version catalog<br/>dependency catalog<br/>[libs.versions.toml]"]
end

subgraph group_tests["Tests"]
  node_unit_tests["Unit tests<br/>jvm tests<br/>[ExampleUnitTest.kt]"]
  node_instrumented_tests["Android tests<br/>instrumented tests"]
end

node_readme["README<br/>overview<br/>[README.md]"]

node_readme -->|"describes"| node_main_activity
node_readme -->|"mentions"| node_backend_setup
node_main_activity -->|"inflates"| node_activity_layout
node_main_activity -->|"hosts"| node_nav_graph
node_nav_graph -->|"routes to"| node_first_fragment
node_nav_graph -->|"routes to"| node_second_fragment
node_first_fragment -->|"renders"| node_first_layout
node_second_fragment -->|"renders"| node_second_layout
node_activity_layout -->|"includes"| node_content_layout
node_first_fragment -->|"uses"| node_resources
node_second_fragment -->|"uses"| node_resources
node_manifest -->|"references"| node_resources
node_manifest -->|"permits"| node_network_stack
node_network_stack -->|"calls"| node_remote_api
node_network_stack -->|"feeds"| node_main_activity
node_backend_setup -->|"implements"| node_remote_api
node_app_build -->|"uses"| node_versions
node_app_build -->|"builds"| node_main_activity
node_app_build -->|"depends on"| node_network_stack
node_unit_tests -->|"verifies"| node_main_activity
node_instrumented_tests -->|"verifies"| node_main_activity

click node_readme "https://github.com/lvin15/voxsight/blob/main/README.md"
click node_main_activity "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt"
click node_first_fragment "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt"
click node_second_fragment "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt"
click node_nav_graph "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/navigation/nav_graph.xml"
click node_activity_layout "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/activity_main.xml"
click node_content_layout "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/content_main.xml"
click node_first_layout "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/fragment_first.xml"
click node_second_layout "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/fragment_second.xml"
click node_resources "https://github.com/lvin15/voxsight/tree/main/mobile/app/src/main/res"
click node_manifest "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/AndroidManifest.xml"
click node_backend_setup "https://github.com/lvin15/voxsight/blob/main/backend/requirements.txt"
click node_app_build "https://github.com/lvin15/voxsight/blob/main/mobile/app/build.gradle.kts"
click node_versions "https://github.com/lvin15/voxsight/blob/main/mobile/gradle/libs.versions.toml"
click node_unit_tests "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/test/java/com/cit/kaido/voxsight/ExampleUnitTest.kt"
click node_instrumented_tests "https://github.com/lvin15/voxsight/blob/main/mobile/app/src/androidTest/java/com/cit/kaido/voxsight/ExampleInstrumentedTest.kt"

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_main_activity,node_first_fragment,node_second_fragment,node_nav_graph,node_activity_layout,node_content_layout,node_first_layout,node_second_layout,node_resources,node_manifest,node_network_stack toneBlue
class node_remote_api,node_backend_setup toneAmber
class node_app_build,node_versions toneMint
class node_unit_tests,node_instrumented_tests toneRose
class node_readme toneNeutral
```

## Components

### Android app

Kotlin/Android client and its UI/runtime pieces

- [MainActivity](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt): activity shell · Hosts the app UI and navigation container · `mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt`
- [First screen](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt): fragment · Primary fragment screen · `mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt`
- [Second screen](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt): fragment · Secondary fragment screen · `mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt`
- [Nav graph](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/navigation/nav_graph.xml): navigation · Fragment navigation wiring · `mobile/app/src/main/res/navigation/nav_graph.xml`
- [Activity layout](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/activity_main.xml): layout · Main activity shell layout · `mobile/app/src/main/res/layout/activity_main.xml`
- [Content layout](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/content_main.xml): layout · Embedded content container layout · `mobile/app/src/main/res/layout/content_main.xml`
- [First layout](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/fragment_first.xml): layout · UI for the first fragment · `mobile/app/src/main/res/layout/fragment_first.xml`
- [Second layout](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/res/layout/fragment_second.xml): layout · UI for the second fragment · `mobile/app/src/main/res/layout/fragment_second.xml`
- [Resources](https://github.com/lvin15/voxsight/tree/main/mobile/app/src/main/res): res bundle · Strings, themes, colors, dimens, and device variants · `mobile/app/src/main/res`
- [Manifest](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/main/AndroidManifest.xml): android manifest · App declaration and permissions · `mobile/app/src/main/AndroidManifest.xml`
- **Network stack**: client networking · Planned Retrofit/Gson/coroutines client boundary

### Python backend

Planned FastAPI server boundary

- **Remote API**: backend service · JSON service consumed by the mobile client
- [Backend setup](https://github.com/lvin15/voxsight/blob/main/backend/requirements.txt): python deps · FastAPI-oriented server dependency placeholder · `backend/requirements.txt`

### Build setup

Dependency and build configuration

- [App build](https://github.com/lvin15/voxsight/blob/main/mobile/app/build.gradle.kts): gradle build · Android module build and dependency wiring · `mobile/app/build.gradle.kts`
- [Version catalog](https://github.com/lvin15/voxsight/blob/main/mobile/gradle/libs.versions.toml): dependency catalog · Central dependency version management · `mobile/gradle/libs.versions.toml`

### Tests

Local and instrumented test targets

- [Unit tests](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/test/java/com/cit/kaido/voxsight/ExampleUnitTest.kt): jvm tests · Local JVM test target · `mobile/app/src/test/java/com/cit/kaido/voxsight/ExampleUnitTest.kt`
- [Android tests](https://github.com/lvin15/voxsight/blob/main/mobile/app/src/androidTest/java/com/cit/kaido/voxsight/ExampleInstrumentedTest.kt): instrumented tests · Device/emulator test target · `mobile/app/src/androidTest/java/com/cit/kaido/voxsight/ExampleInstrumentedTest.kt`

### Other components

- [README](https://github.com/lvin15/voxsight/blob/main/README.md): overview · Project framing and intended stack · `README.md`

## Connections

- README → MainActivity: describes · README frames the Android client as the main product
- README → Backend setup: mentions · README indicates a FastAPI backend is being set up
- MainActivity → Activity layout: inflates · Activity uses the shell layout
- MainActivity → Nav graph: hosts · Activity is the navigation host
- Nav graph → First screen: routes to · Navigation graph connects the first screen
- Nav graph → Second screen: routes to · Navigation graph connects the second screen
- First screen → First layout: renders · First fragment is backed by its layout
- Second screen → Second layout: renders · Second fragment is backed by its layout
- Activity layout → Content layout: includes · Activity shell composes the content container
- First screen → Resources: uses · Fragment UI pulls strings, themes, and dimens from resources
- Second screen → Resources: uses · Fragment UI pulls strings, themes, and dimens from resources
- Manifest → Resources: references · Manifest and resource configuration work together
- Manifest → Network stack: permits · Internet permission supports remote API access
- Network stack → Remote API: calls · Planned HTTP client talks to the backend service
- Network stack → MainActivity: feeds · Fetched data would flow back into the UI shell
- Backend setup → Remote API: implements · Dependency setup points toward a FastAPI service
- App build → Version catalog: uses · App build is driven by shared dependency versions
- App build → MainActivity: builds · Build module compiles the client app code
- App build → Network stack: depends on · Build includes the client networking libraries
- Unit tests → MainActivity: verifies · Local tests cover Kotlin-side app logic
- Android tests → MainActivity: verifies · Instrumented tests cover Android runtime behavior
