# vishwanath-06/speak-to-repo architecture

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

- Interactive diagram: https://gitdiagram.com/vishwanath-06/speak-to-repo
- Repository: https://github.com/vishwanath-06/speak-to-repo

## Overview

Speak-to-Repo turns recorded design reviews and live voice overrides into repository-grounded architecture diagrams, patches, and ADRs. Its main workflow harvests repository symbols to bias speech recognition, indexes source and timestamped meeting segments, retrieves relevant material for compilation, and presents or records the resulting artifacts. The live studio and event-sourced CLI are separate entry points into that workflow. The README documents several studio behaviors beyond the sampled excerpts; edges for those are cited to the README, while unsampled implementation details are not inferred.

Main entry points: [`scripts/demo_studio.py`](https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/demo_studio.py) (Live Studio), [`workers/gemma_indexer.py`](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/gemma_indexer.py) (Vector Indexer), [`scripts/cordis_session_runner.py`](https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/cordis_session_runner.py) (Session Runner), [`workers/repo_compiler.py`](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/repo_compiler.py) (Artifact Compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Review Ingestion"]
  node_voice["Voice Ingest<br/>[whistle_ingest.py]"]
  node_symbols["AST Symbols<br/>[ast_extractor.py]"]
  node_transcript["Timed Transcript"]
end

subgraph group_grounding["Repository Grounding"]
  node_indexer["Vector Indexer<br/>[gemma_indexer.py]"]
  node_embedder["Gemma Embedder<br/>[gemma_indexer.py]"]
  node_vectorstore[("LanceDB Index")]
  node_targetrepo["Target Repository"]
end

subgraph group_compile["Compilation"]
  node_compiler["Artifact Compiler<br/>[repo_compiler.py]"]
  node_topology["Mermaid Topology<br/>[repo_compiler.py]"]
  node_patch["Unified Git Patch<br/>[demo_studio.py]"]
  node_adr["Compiled ADR"]
end

subgraph group_interfaces["User Interfaces"]
  node_studio["Live Studio<br/>[demo_studio.py]"]
  node_session["Session Runner"]
  node_eventlog[("Session Events")]
end

node_engineer(("Engineer"))
node_browser(("Browser User"))

node_engineer -->|"uses"| node_studio
node_engineer -->|"starts session"| node_session
node_studio -->|"transcribes override"| node_voice
node_voice -->|"harvests keywords"| node_symbols
node_voice -->|"writes segments"| node_transcript
node_targetrepo -->|"indexes source"| node_indexer
node_transcript -->|"indexes segments"| node_indexer
node_indexer -->|"embeds records"| node_embedder
node_embedder -->|"writes vectors"| node_vectorstore
node_studio -->|"queries index"| node_indexer
node_compiler -->|"retrieves matches"| node_indexer
node_compiler -->|"reads source context"| node_targetrepo
node_compiler -->|"renders topology"| node_topology
node_studio -->|"compiles override"| node_patch
node_studio -->|"presents ADR"| node_adr
node_session -->|"runs ingest"| node_voice
node_session -->|"runs indexing"| node_indexer
node_session -->|"runs compilation"| node_compiler
node_session -->|"appends events"| node_eventlog
node_browser -->|"opens studio"| node_studio

click node_studio "https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/demo_studio.py"
click node_session "https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/cordis_session_runner.py"
click node_voice "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/whistle_ingest.py"
click node_symbols "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/ast_extractor.py"
click node_transcript "https://github.com/vishwanath-06/speak-to-repo/tree/main/storage/transcripts"
click node_indexer "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/gemma_indexer.py"
click node_embedder "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/gemma_indexer.py"
click node_compiler "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/repo_compiler.py"
click node_topology "https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/repo_compiler.py"
click node_patch "https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/demo_studio.py"
click node_adr "https://github.com/vishwanath-06/speak-to-repo/tree/main/storage/compiled_docs"
click node_eventlog "https://github.com/vishwanath-06/speak-to-repo/blob/main/storage/sessions/session_events.jsonl"

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_voice,node_symbols,node_transcript,node_browser toneBlue
class node_indexer,node_embedder,node_vectorstore,node_targetrepo toneAmber
class node_compiler,node_topology,node_patch,node_adr toneMint
class node_studio,node_session,node_eventlog toneRose
class node_engineer toneIndigo
```

## Components

### Review Ingestion

- [Voice Ingest](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/whistle_ingest.py): `workers/whistle_ingest.py`
- [AST Symbols](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/ast_extractor.py): `workers/ast_extractor.py`
- [Timed Transcript](https://github.com/vishwanath-06/speak-to-repo/tree/main/storage/transcripts): `storage/transcripts`

### Repository Grounding

- [Vector Indexer](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/gemma_indexer.py): `workers/gemma_indexer.py`
- [Gemma Embedder](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/gemma_indexer.py): `workers/gemma_indexer.py`
- **LanceDB Index**
- **Target Repository**

### Compilation

- [Artifact Compiler](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/repo_compiler.py): `workers/repo_compiler.py`
- [Mermaid Topology](https://github.com/vishwanath-06/speak-to-repo/blob/main/workers/repo_compiler.py): `workers/repo_compiler.py`
- [Unified Git Patch](https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/demo_studio.py): `scripts/demo_studio.py`
- [Compiled ADR](https://github.com/vishwanath-06/speak-to-repo/tree/main/storage/compiled_docs): `storage/compiled_docs`

### User Interfaces

- [Live Studio](https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/demo_studio.py): `scripts/demo_studio.py`
- [Session Runner](https://github.com/vishwanath-06/speak-to-repo/blob/main/scripts/cordis_session_runner.py): `scripts/cordis_session_runner.py`
- [Session Events](https://github.com/vishwanath-06/speak-to-repo/blob/main/storage/sessions/session_events.jsonl): `storage/sessions/session_events.jsonl`

### Other components

- **Engineer**
- **Browser User**

## Connections

- Engineer → Live Studio: uses (evidence: `README.md`)
- Engineer → Session Runner: starts session (evidence: `README.md`)
- Live Studio → Voice Ingest: transcribes override (evidence: `README.md`)
- Voice Ingest → AST Symbols: harvests keywords (evidence: `workers/whistle_ingest.py`)
- Voice Ingest → Timed Transcript: writes segments (evidence: `workers/whistle_ingest.py`)
- Target Repository → Vector Indexer: indexes source (evidence: `README.md`)
- Timed Transcript → Vector Indexer: indexes segments (evidence: `README.md`)
- Vector Indexer → Gemma Embedder: embeds records (evidence: `workers/gemma_indexer.py`)
- Gemma Embedder → LanceDB Index: writes vectors (evidence: `README.md`)
- Live Studio → Vector Indexer: queries index (evidence: `README.md`)
- Artifact Compiler → Vector Indexer: retrieves matches (evidence: `workers/repo_compiler.py`)
- Artifact Compiler → Target Repository: reads source context (evidence: `workers/repo_compiler.py`)
- Artifact Compiler → Mermaid Topology: renders topology (evidence: `workers/repo_compiler.py`)
- Live Studio → Unified Git Patch: compiles override (evidence: `README.md`)
- Live Studio → Compiled ADR: presents ADR (evidence: `README.md`)
- Session Runner → Voice Ingest: runs ingest (evidence: `scripts/cordis_session_runner.py`)
- Session Runner → Vector Indexer: runs indexing (evidence: `scripts/cordis_session_runner.py`)
- Session Runner → Artifact Compiler: runs compilation (evidence: `scripts/cordis_session_runner.py`)
- Session Runner → Session Events: appends events (evidence: `scripts/cordis_session_runner.py`)
- Browser User → Live Studio: opens studio (evidence: `README.md`)