# kodestar/audiosilo-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/kodestar/audiosilo-bridge
- Repository: https://github.com/kodestar/audiosilo-bridge

## Overview

AudioSilo Bridge is an always-on companion that pairs with an AudioSilo server, validates shared-library mappings, and runs queued media jobs while the server can remain read-only. The main workflow is server job dispatch → Bridge job handling → media processing and optional isolated agent work → sidecar results saved alongside books. Separate branches cover podcasts, Audible backups and listening-place sync, community contributions, chapter detection, and read-along alignment; remote ASR workers provide transcription. The README documents these capabilities, but unsampled implementations are represented at their enclosing directories.

Main entry points: [`internal/jobs`](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/jobs) (Job handlers), [`internal/app/app.go`](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/app/app.go) (Bridge runtime), [`internal/pipeline/pipeline.go`](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/pipeline/pipeline.go) (Transcription pipeline), [`internal/api`](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/api) (Bridge API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bridge["Bridge service"]
  node_entry["Bridge entrypoint<br/>[main.go]"]
  node_app["Bridge runtime<br/>[app.go]"]
  node_api["Bridge API"]
  node_jobs["Job handlers"]
  node_store[("Persistent state")]
  node_mapping["Library mapping checks"]
end

subgraph group_processing["Media processing"]
  node_pipeline["Transcription pipeline<br/>[pipeline.go]"]
  node_audio["Audio and ASR"]
  node_agent["Isolated agent runner<br/>[main.go]"]
  node_sidecars["Generated sidecars"]
  node_chapters["Chapter detection"]
  node_readalong["Read-along alignment"]
  node_podcasts["Podcast jobs"]
  node_audible["Audible jobs and sync"]
end

subgraph group_integrations["External integrations"]
  node_server["AudioSilo server"]
  node_contrib["Community contributions<br/>[service.go]"]
  node_metadata["Metadata service"]
  node_worker["Remote ASR worker<br/>[worker.go]"]
end

subgraph group_interface["Operator interface"]
  node_web["Bridge web page<br/>[App.tsx]"]
  node_webclient["Web API client<br/>[client.ts]"]
end

node_admin(("Administrator"))

node_admin -->|"starts jobs"| node_server
node_entry -->|"starts runtime"| node_app
node_app -->|"serves API"| node_api
node_web -.->|"uses client"| node_webclient
node_webclient -.->|"requests API"| node_api
node_app -->|"heartbeats and requests jobs"| node_server
node_server -->|"returns jobs"| node_app
node_app -->|"checks mappings"| node_mapping
node_app -->|"dispatches jobs"| node_jobs
node_jobs -.->|"persists job state"| node_store
node_jobs -.->|"runs generation"| node_pipeline
node_pipeline -->|"transcribes audio"| node_audio
node_pipeline -.->|"invokes isolated agents"| node_agent
node_pipeline -.->|"produces results"| node_sidecars
node_jobs -.->|"runs chapter detection"| node_chapters
node_jobs -.->|"runs alignment"| node_readalong
node_jobs -.->|"runs podcast tasks"| node_podcasts
node_jobs -.->|"runs Audible tasks"| node_audible
node_jobs -->|"handles contributions"| node_contrib
node_contrib -.->|"publishes metadata"| node_metadata
node_worker -->|"claims and uploads transcripts"| node_api
node_api -->|"serves worker audio"| node_audio

click node_entry "https://github.com/kodestar/audiosilo-bridge/blob/main/cmd/audiosilo-bridge/main.go"
click node_app "https://github.com/kodestar/audiosilo-bridge/blob/main/internal/app/app.go"
click node_api "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/api"
click node_jobs "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/jobs"
click node_store "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/store"
click node_mapping "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/mapping"
click node_pipeline "https://github.com/kodestar/audiosilo-bridge/blob/main/internal/pipeline/pipeline.go"
click node_audio "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/asr"
click node_agent "https://github.com/kodestar/audiosilo-bridge/blob/main/internal/agentrun/main.go"
click node_sidecars "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/generate"
click node_chapters "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/chapterdetect"
click node_readalong "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/readalong"
click node_podcasts "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/podcastjob"
click node_audible "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/audiblejob"
click node_contrib "https://github.com/kodestar/audiosilo-bridge/blob/main/internal/contrib/service.go"
click node_metadata "https://github.com/kodestar/audiosilo-bridge/tree/main/internal/metaops"
click node_worker "https://github.com/kodestar/audiosilo-bridge/blob/main/internal/worker/worker.go"
click node_web "https://github.com/kodestar/audiosilo-bridge/blob/main/web/src/App.tsx"
click node_webclient "https://github.com/kodestar/audiosilo-bridge/blob/main/web/src/api/client.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_entry,node_app,node_api,node_jobs,node_store,node_mapping toneBlue
class node_pipeline,node_audio,node_agent,node_sidecars,node_chapters,node_readalong,node_podcasts,node_audible toneAmber
class node_server,node_contrib,node_metadata,node_worker toneMint
class node_web,node_webclient toneRose
class node_admin toneIndigo
```

## Components

### Bridge service

- [Bridge entrypoint](https://github.com/kodestar/audiosilo-bridge/blob/main/cmd/audiosilo-bridge/main.go): `cmd/audiosilo-bridge/main.go`
- [Bridge runtime](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/app/app.go): `internal/app/app.go`
- [Bridge API](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/api): `internal/api`
- [Job handlers](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/jobs): `internal/jobs`
- [Persistent state](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/store): `internal/store`
- [Library mapping checks](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/mapping): `internal/mapping`

### Media processing

- [Transcription pipeline](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/pipeline/pipeline.go): `internal/pipeline/pipeline.go`
- [Audio and ASR](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/asr): `internal/asr`
- [Isolated agent runner](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/agentrun/main.go): `internal/agentrun/main.go`
- [Generated sidecars](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/generate): `internal/generate`
- [Chapter detection](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/chapterdetect): `internal/chapterdetect`
- [Read-along alignment](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/readalong): `internal/readalong`
- [Podcast jobs](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/podcastjob): `internal/podcastjob`
- [Audible jobs and sync](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/audiblejob): `internal/audiblejob`

### External integrations

- **AudioSilo server**
- [Community contributions](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/contrib/service.go): `internal/contrib/service.go`
- [Metadata service](https://github.com/kodestar/audiosilo-bridge/tree/main/internal/metaops): `internal/metaops`
- [Remote ASR worker](https://github.com/kodestar/audiosilo-bridge/blob/main/internal/worker/worker.go): `internal/worker/worker.go`

### Operator interface

- [Bridge web page](https://github.com/kodestar/audiosilo-bridge/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/kodestar/audiosilo-bridge/blob/main/web/src/api/client.ts): `web/src/api/client.ts`

### Other components

- **Administrator**

## Connections

- Administrator → AudioSilo server: starts jobs (evidence: `README.md`)
- Bridge entrypoint → Bridge runtime: starts runtime (evidence: `cmd/audiosilo-bridge/main.go`)
- Bridge runtime → Bridge API: serves API (evidence: `internal/app/app.go`)
- Bridge web page → Web API client: uses client
- Web API client → Bridge API: requests API
- Bridge runtime → AudioSilo server: heartbeats and requests jobs (evidence: `README.md`)
- AudioSilo server → Bridge runtime: returns jobs (evidence: `README.md`)
- Bridge runtime → Library mapping checks: checks mappings (evidence: `README.md`)
- Bridge runtime → Job handlers: dispatches jobs (evidence: `internal/app/app.go`)
- Job handlers → Persistent state: persists job state
- Job handlers → Transcription pipeline: runs generation
- Transcription pipeline → Audio and ASR: transcribes audio (evidence: `internal/pipeline/pipeline.go`)
- Transcription pipeline → Isolated agent runner: invokes isolated agents
- Transcription pipeline → Generated sidecars: produces results
- Job handlers → Chapter detection: runs chapter detection
- Job handlers → Read-along alignment: runs alignment
- Job handlers → Podcast jobs: runs podcast tasks
- Job handlers → Audible jobs and sync: runs Audible tasks
- Job handlers → Community contributions: handles contributions
- Community contributions → Metadata service: publishes metadata
- Remote ASR worker → Bridge API: claims and uploads transcripts (evidence: `README.md`)
- Bridge API → Audio and ASR: serves worker audio (evidence: `internal/api/workers.go`)
