How lvin15/voxsight works
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: MainActivity.kt MainActivity · build.gradle.kts App build · FirstFragment.kt First screen · SecondFragment.kt Second screen
Components 18
Android app
Kotlin/Android client and its UI/runtime pieces
- MainActivity · Hosts the app UI and navigation container
mobile/app/src/main/java/com/cit/kaido/voxsight/MainActivity.kt - First screen · Primary fragment screen
mobile/app/src/main/java/com/cit/kaido/voxsight/FirstFragment.kt - Second screen · Secondary fragment screen
mobile/app/src/main/java/com/cit/kaido/voxsight/SecondFragment.kt - Nav graph · Fragment navigation wiring
mobile/app/src/main/res/navigation/nav_graph.xml - Activity layout · Main activity shell layout
mobile/app/src/main/res/layout/activity_main.xml - Content layout · Embedded content container layout
mobile/app/src/main/res/layout/content_main.xml - First layout · UI for the first fragment
mobile/app/src/main/res/layout/fragment_first.xml - Second layout · UI for the second fragment
mobile/app/src/main/res/layout/fragment_second.xml - Resources · Strings, themes, colors, dimens, and device variants
mobile/app/src/main/res - Manifest · App declaration and permissions
mobile/app/src/main/AndroidManifest.xml - Network stack · Planned Retrofit/Gson/coroutines client boundary
Python backend
Planned FastAPI server boundary
- Remote API · JSON service consumed by the mobile client
- Backend setup · FastAPI-oriented server dependency placeholder
backend/requirements.txt
Build setup
Dependency and build configuration
- App build · Android module build and dependency wiring
mobile/app/build.gradle.kts - Version catalog · Central dependency version management
mobile/gradle/libs.versions.toml
Tests
Local and instrumented test targets
- Unit tests · Local JVM test target
mobile/app/src/test/java/com/cit/kaido/voxsight/ExampleUnitTest.kt - Android tests · Device/emulator test target
mobile/app/src/androidTest/java/com/cit/kaido/voxsight/ExampleInstrumentedTest.kt
Other components
- README · Project framing and intended stack
README.md
Connections 21
- 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