# ktaffy/vault architecture

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

- Interactive diagram: https://gitdiagram.com/ktaffy/vault
- Repository: https://github.com/ktaffy/vault

## Overview

Vault is a mobile music-discovery and artist-promotion app: listeners hear short snippets and swipe to save/follow or skip; artists upload a single 15-second snippet and track its plays. The graph shows the mobile entry points and API layers, plus the Go services for accounts, snippet management, feed selection, and swipe recording. Backend wiring is based on the bootstrap and router; sampled service excerpts support only some internal calls, so uncertain repository-level and screen-level links are omitted.

Main entry points: [`backend/router/router.go`](https://github.com/ktaffy/vault/blob/main/backend/router/router.go) (HTTP router), [`frontend/src/services/api/auth.ts`](https://github.com/ktaffy/vault/blob/main/frontend/src/services/api/auth.ts) (API services), [`backend/db/db.go`](https://github.com/ktaffy/vault/blob/main/backend/db/db.go) (PostgreSQL), [`frontend/app/(tabs)/index.tsx`](https://github.com/ktaffy/vault/blob/main/frontend/app/(tabs)/index.tsx) (Listener screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_auth_ui["Auth screens<br/>[login.tsx]"]
  node_listener_ui["Listener screens<br/>[index.tsx]"]
  node_artist_ui["Artist screens<br/>[upload.tsx]"]
  node_auth_hook["Auth hook<br/>[useAuth.ts]"]
  node_api_services["API services<br/>[auth.ts]"]
  node_api_client["API client<br/>[client.ts]"]
  node_audio_playback["Audio playback"]
  node_secure_storage[("Secure storage<br/>[SecureStorage.ts]")]
end

subgraph group_api["Backend API"]
  node_router["HTTP router<br/>[router.go]"]
end

subgraph group_content["Music discovery"]
  node_snippet_handler["Snippet handlers<br/>[snippet_handler.go]"]
  node_snippet_service["Snippet service<br/>[snippet_service.go]"]
  node_snippet_repo["Snippet repository<br/>[snippet_repo.go]"]
  node_feed_handler["Feed handler<br/>[feed_handler.go]"]
  node_feed_service["Feed selection<br/>[feed_service.go]"]
  node_feed_repo["Feed repository<br/>[feed_repo.go]"]
  node_swipe_handler["Swipe handler<br/>[swipe_handler.go]"]
  node_swipe_service["Swipe service<br/>[swipe_service.go]"]
  node_swipe_repo["Swipe repository<br/>[swipe_repo.go]"]
  node_jobs["Feed jobs<br/>[jobs.go]"]
end

subgraph group_accounts["Accounts"]
  node_user_handler["User handlers<br/>[user_handler.go]"]
  node_user_service["User service<br/>[user_service.go]"]
  node_user_repo["User repository<br/>[user_repo.go]"]
end

node_listener(("Listener"))
node_artist(("Artist"))
node_postgres[("PostgreSQL<br/>[db.go]")]
node_s3[("AWS S3")]
node_email["Email service"]

node_listener -->|"signs in"| node_auth_ui
node_listener -->|"discovers music"| node_listener_ui
node_artist -->|"manages music"| node_artist_ui
node_auth_ui -->|"uses auth"| node_auth_hook
node_auth_hook -->|"requests auth"| node_api_services
node_auth_hook -->|"stores credentials"| node_secure_storage
node_listener_ui -->|"requests feed"| node_api_services
node_artist_ui -->|"requests artist data"| node_api_services
node_listener_ui -->|"plays snippets"| node_audio_playback
node_api_services -->|"sends requests"| node_api_client
node_api_client -->|"HTTP requests"| node_router
node_router -->|"routes account requests"| node_user_handler
node_router -->|"routes snippet requests"| node_snippet_handler
node_router -->|"routes feed requests"| node_feed_handler
node_router -->|"routes swipe requests"| node_swipe_handler
node_user_handler -->|"calls"| node_user_service
node_user_service -->|"reads and writes"| node_user_repo
node_user_repo -->|"persists account data"| node_postgres
node_user_service -.->|"sends account email"| node_email
node_snippet_handler -->|"calls"| node_snippet_service
node_snippet_service -->|"creates and reads"| node_snippet_repo
node_snippet_repo -->|"persists snippet data"| node_postgres
node_snippet_service -->|"uploads media"| node_s3
node_feed_handler -->|"requests next snippet"| node_feed_service
node_feed_service -->|"reads candidates and queue"| node_feed_repo
node_feed_repo -->|"reads feed data"| node_postgres
node_jobs -->|"refills queues"| node_feed_service
node_swipe_handler -->|"records action"| node_swipe_service
node_swipe_service -->|"validates snippet"| node_snippet_repo
node_swipe_service -->|"records and reads swipes"| node_swipe_repo
node_swipe_repo -->|"persists swipe data"| node_postgres

click node_auth_ui "https://github.com/ktaffy/vault/blob/main/frontend/app/(auth)/login.tsx"
click node_listener_ui "https://github.com/ktaffy/vault/blob/main/frontend/app/(tabs)/index.tsx"
click node_artist_ui "https://github.com/ktaffy/vault/blob/main/frontend/app/(tabs)/artist/upload.tsx"
click node_auth_hook "https://github.com/ktaffy/vault/blob/main/frontend/src/hooks/useAuth.ts"
click node_api_services "https://github.com/ktaffy/vault/blob/main/frontend/src/services/api/auth.ts"
click node_api_client "https://github.com/ktaffy/vault/blob/main/frontend/src/services/api/client.ts"
click node_audio_playback "https://github.com/ktaffy/vault/blob/main/frontend/src/hooks/useAudioPlayback.ts"
click node_secure_storage "https://github.com/ktaffy/vault/blob/main/frontend/src/services/storage/SecureStorage.ts"
click node_router "https://github.com/ktaffy/vault/blob/main/backend/router/router.go"
click node_user_handler "https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_handler.go"
click node_user_service "https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_service.go"
click node_user_repo "https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_repo.go"
click node_snippet_handler "https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_handler.go"
click node_snippet_service "https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_service.go"
click node_snippet_repo "https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_repo.go"
click node_feed_handler "https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_handler.go"
click node_feed_service "https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_service.go"
click node_feed_repo "https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_repo.go"
click node_swipe_handler "https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_handler.go"
click node_swipe_service "https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_service.go"
click node_swipe_repo "https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_repo.go"
click node_jobs "https://github.com/ktaffy/vault/blob/main/backend/jobs/jobs.go"
click node_postgres "https://github.com/ktaffy/vault/blob/main/backend/db/db.go"

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_auth_ui,node_listener_ui,node_artist_ui,node_auth_hook,node_api_services,node_api_client,node_audio_playback,node_secure_storage toneBlue
class node_router,node_postgres,node_s3 toneAmber
class node_snippet_handler,node_snippet_service,node_snippet_repo,node_feed_handler,node_feed_service,node_feed_repo,node_swipe_handler,node_swipe_service,node_swipe_repo,node_jobs toneMint
class node_user_handler,node_user_service,node_user_repo toneRose
class node_listener,node_artist,node_email toneIndigo
```

## Components

### Mobile app

- [Auth screens](https://github.com/ktaffy/vault/blob/main/frontend/app/(auth)/login.tsx): `frontend/app/(auth)/login.tsx`
- [Listener screens](https://github.com/ktaffy/vault/blob/main/frontend/app/(tabs)/index.tsx): `frontend/app/(tabs)/index.tsx`
- [Artist screens](https://github.com/ktaffy/vault/blob/main/frontend/app/(tabs)/artist/upload.tsx): `frontend/app/(tabs)/artist/upload.tsx`
- [Auth hook](https://github.com/ktaffy/vault/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [API services](https://github.com/ktaffy/vault/blob/main/frontend/src/services/api/auth.ts): `frontend/src/services/api/auth.ts`
- [API client](https://github.com/ktaffy/vault/blob/main/frontend/src/services/api/client.ts): `frontend/src/services/api/client.ts`
- [Audio playback](https://github.com/ktaffy/vault/blob/main/frontend/src/hooks/useAudioPlayback.ts): `frontend/src/hooks/useAudioPlayback.ts`
- [Secure storage](https://github.com/ktaffy/vault/blob/main/frontend/src/services/storage/SecureStorage.ts): `frontend/src/services/storage/SecureStorage.ts`

### Backend API

- [HTTP router](https://github.com/ktaffy/vault/blob/main/backend/router/router.go): `backend/router/router.go`

### Music discovery

- [Snippet handlers](https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_handler.go): `backend/internal/snippet/snippet_handler.go`
- [Snippet service](https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_service.go): `backend/internal/snippet/snippet_service.go`
- [Snippet repository](https://github.com/ktaffy/vault/blob/main/backend/internal/snippet/snippet_repo.go): `backend/internal/snippet/snippet_repo.go`
- [Feed handler](https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_handler.go): `backend/internal/feed/feed_handler.go`
- [Feed selection](https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_service.go): `backend/internal/feed/feed_service.go`
- [Feed repository](https://github.com/ktaffy/vault/blob/main/backend/internal/feed/feed_repo.go): `backend/internal/feed/feed_repo.go`
- [Swipe handler](https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_handler.go): `backend/internal/swipe/swipe_handler.go`
- [Swipe service](https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_service.go): `backend/internal/swipe/swipe_service.go`
- [Swipe repository](https://github.com/ktaffy/vault/blob/main/backend/internal/swipe/swipe_repo.go): `backend/internal/swipe/swipe_repo.go`
- [Feed jobs](https://github.com/ktaffy/vault/blob/main/backend/jobs/jobs.go): `backend/jobs/jobs.go`

### Accounts

- [User handlers](https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_handler.go): `backend/internal/user/user_handler.go`
- [User service](https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_service.go): `backend/internal/user/user_service.go`
- [User repository](https://github.com/ktaffy/vault/blob/main/backend/internal/user/user_repo.go): `backend/internal/user/user_repo.go`

### Other components

- **Listener**
- **Artist**
- [PostgreSQL](https://github.com/ktaffy/vault/blob/main/backend/db/db.go): `backend/db/db.go`
- **AWS S3**
- **Email service**

## Connections

- Listener → Auth screens: signs in
- Listener → Listener screens: discovers music
- Artist → Artist screens: manages music
- Auth screens → Auth hook: uses auth
- Auth hook → API services: requests auth
- Auth hook → Secure storage: stores credentials
- Listener screens → API services: requests feed
- Artist screens → API services: requests artist data
- Listener screens → Audio playback: plays snippets
- API services → API client: sends requests
- API client → HTTP router: HTTP requests
- HTTP router → User handlers: routes account requests
- HTTP router → Snippet handlers: routes snippet requests
- HTTP router → Feed handler: routes feed requests
- HTTP router → Swipe handler: routes swipe requests
- User handlers → User service: calls
- User service → User repository: reads and writes
- User repository → PostgreSQL: persists account data
- User service → Email service: sends account email
- Snippet handlers → Snippet service: calls
- Snippet service → Snippet repository: creates and reads
- Snippet repository → PostgreSQL: persists snippet data
- Snippet service → AWS S3: uploads media
- Feed handler → Feed selection: requests next snippet
- Feed selection → Feed repository: reads candidates and queue
- Feed repository → PostgreSQL: reads feed data
- Feed jobs → Feed selection: refills queues
- Swipe handler → Swipe service: records action
- Swipe service → Snippet repository: validates snippet
- Swipe service → Swipe repository: records and reads swipes
- Swipe repository → PostgreSQL: persists swipe data