# kju4q/ai-weekend-builds architecture

> Architecture diagram of the GitHub repository kju4q/ai-weekend-builds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kju4q/ai-weekend-builds
- Repository: https://github.com/kju4q/ai-weekend-builds

## Overview

AI Weekend Builds is a collection of independent, runnable AI projects—not one application. Each project turns a user’s input into a distinct result, from searchable personal data and photo timelines to simulations and learning agents. The graph preserves the projects listed in the README and file tree; sampled internal links show only relationships supported by excerpts or the SOURCE INDEX. Several project implementations were not sampled, so their internal flows are left unspecified.

Main entry points: [`vol-5/05-the-arena/train.py`](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/train.py) (Q-Learning), [`vol-3/01-life-admin-brain/embeddings.py`](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/embeddings.py) (Local Embeddings), [`vol-5/05-the-arena/arena.py`](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/arena.py) (Game Environment), [`vol-5/05-the-arena/watch.py`](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/watch.py) (Agent Replay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vol1["Vol 1 Projects"]
  node_rag["Personal RAG<br/>[rag.py]"]
  node_research["Research Crew<br/>[crew.py]"]
  node_coding["Coding Agent<br/>[agent.py]"]
end

subgraph group_life["Life Tools"]
  node_life_ingest["Document Ingest<br/>[ingest.py]"]
  node_life_embed["Local Embeddings<br/>[embeddings.py]"]
  node_life_ask["Document Q&amp;A<br/>[ask.py]"]
  node_money["Money Map<br/>[money_map.py]"]
  node_record["Voice Recording<br/>[record.py]"]
  node_transcribe["Transcription<br/>[transcribe.py]"]
  node_summary["Journal Summary<br/>[summary.py]"]
  node_dashboard["Life Dashboard<br/>[server.py]"]
  node_decision["Decision Simulator<br/>[simulate.py]"]
end

subgraph group_data["Personal Data"]
  node_past_ingest["Writing Ingest<br/>[ingest.py]"]
  node_past_ask["Past-You Search<br/>[ask.py]"]
  node_pattern["Photo Timeline<br/>[analyze.py]"]
  node_photo["Photo Analysis<br/>[photolib.py]"]
  node_lookout["Lookout<br/>[check.py]"]
  node_personal_api["Personal API<br/>[server.py]"]
  node_freedom["Freedom Calculator<br/>[simulate.py]"]
end

subgraph group_vol5["Vol 5 Projects"]
  node_content["Content Brain<br/>[content_brain.py]"]
  node_content_ask["Content Q&amp;A<br/>[ask.py]"]
  node_content_board["Content Board<br/>[build_board.py]"]
  node_context["Context Assembly<br/>[context.py]"]
  node_memory["Corrections Memory<br/>[memory.py]"]
  node_nutrition["Nutrition Lens<br/>[lens.py]"]
  node_nutrition_rules["Meal Rules<br/>[rules.py]"]
  node_motion["Motion Studio<br/>[generate.py]"]
  node_render["Motion Rendering<br/>[render.py]"]
  node_arena["Game Environment<br/>[arena.py]"]
  node_train["Q-Learning<br/>[train.py]"]
  node_watch["Agent Replay<br/>[watch.py]"]
end

node_user(("User"))

node_user -->|"asks about documents"| node_rag
node_user -->|"requests research"| node_research
node_user -->|"provides issue"| node_coding
node_user -->|"adds documents"| node_life_ingest
node_user -->|"asks questions"| node_life_ask
node_user -->|"provides bank CSV"| node_money
node_user -->|"records voice"| node_record
node_user -->|"views daily scene"| node_dashboard
node_user -->|"simulates decision"| node_decision
node_user -->|"indexes writing"| node_past_ingest
node_user -->|"searches memories"| node_past_ask
node_user -->|"analyzes photos"| node_pattern
node_user -->|"sets watched sources"| node_lookout
node_user -->|"uses personal endpoints"| node_personal_api
node_user -->|"sets assumptions"| node_freedom
node_user -->|"files content"| node_content_board
node_user -->|"assembles context"| node_context
node_user -->|"provides meal"| node_nutrition
node_user -->|"generates motion"| node_motion
node_user -->|"trains agent"| node_train
node_user -->|"plays game"| node_arena
node_life_ingest -->|"uses embeddings"| node_life_embed
node_life_ask -->|"uses embeddings"| node_life_embed
node_past_ingest -->|"uses embeddings"| node_life_embed
node_pattern -->|"delegates analysis"| node_photo
node_content_ask -->|"imports shared logic"| node_content
node_content_board -->|"imports shared logic"| node_content
node_context -->|"reads corrections"| node_memory
node_nutrition -->|"uses meal rules"| node_nutrition_rules
node_train -->|"trains in environment"| node_arena
node_watch -->|"uses environment"| node_arena
node_watch -->|"loads training output"| node_train

click node_rag "https://github.com/kju4q/ai-weekend-builds/blob/main/03-personal-rag-assistant/rag.py"
click node_research "https://github.com/kju4q/ai-weekend-builds/blob/main/04-multi-agent-research-crew/crew.py"
click node_coding "https://github.com/kju4q/ai-weekend-builds/blob/main/05-autonomous-coding-agent/agent.py"
click node_life_ingest "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/ingest.py"
click node_life_embed "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/embeddings.py"
click node_life_ask "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/ask.py"
click node_money "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/02-money-map/money_map.py"
click node_record "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/record.py"
click node_transcribe "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/transcribe.py"
click node_summary "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/summary.py"
click node_dashboard "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/04-ambient-life-dashboard/server.py"
click node_decision "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/05-decision-simulator/simulate.py"
click node_past_ingest "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/01-past-you-searcher/ingest.py"
click node_past_ask "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/01-past-you-searcher/ask.py"
click node_pattern "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/02-pattern-mirror/analyze.py"
click node_photo "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/02-pattern-mirror/photolib.py"
click node_lookout "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/03-lookout/check.py"
click node_personal_api "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/04-personal-api/server.py"
click node_freedom "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/05-freedom-calculator/simulate.py"
click node_content "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/content_brain.py"
click node_content_ask "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/ask.py"
click node_content_board "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/build_board.py"
click node_context "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/02-context-layer/context.py"
click node_memory "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/02-context-layer/memory.py"
click node_nutrition "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/03-nutrition-lens/lens.py"
click node_nutrition_rules "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/03-nutrition-lens/rules.py"
click node_motion "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/04-motion-studio/generate.py"
click node_render "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/04-motion-studio/render.py"
click node_arena "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/arena.py"
click node_train "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/train.py"
click node_watch "https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/watch.py"

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_rag,node_research,node_coding,node_user toneBlue
class node_life_ingest,node_life_embed,node_life_ask,node_money,node_record,node_transcribe,node_summary,node_dashboard,node_decision toneAmber
class node_past_ingest,node_past_ask,node_pattern,node_photo,node_lookout,node_personal_api,node_freedom toneMint
class node_content,node_content_ask,node_content_board,node_context,node_memory,node_nutrition,node_nutrition_rules,node_motion,node_render,node_arena,node_train,node_watch toneRose
```

## Components

### Vol 1 Projects

- [Personal RAG](https://github.com/kju4q/ai-weekend-builds/blob/main/03-personal-rag-assistant/rag.py): `03-personal-rag-assistant/rag.py`
- [Research Crew](https://github.com/kju4q/ai-weekend-builds/blob/main/04-multi-agent-research-crew/crew.py): `04-multi-agent-research-crew/crew.py`
- [Coding Agent](https://github.com/kju4q/ai-weekend-builds/blob/main/05-autonomous-coding-agent/agent.py): `05-autonomous-coding-agent/agent.py`

### Life Tools

- [Document Ingest](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/ingest.py): `vol-3/01-life-admin-brain/ingest.py`
- [Local Embeddings](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/embeddings.py): `vol-3/01-life-admin-brain/embeddings.py`
- [Document Q&A](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/01-life-admin-brain/ask.py): `vol-3/01-life-admin-brain/ask.py`
- [Money Map](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/02-money-map/money_map.py): `vol-3/02-money-map/money_map.py`
- [Voice Recording](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/record.py): `vol-3/03-offline-voice-journal/record.py`
- [Transcription](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/transcribe.py): `vol-3/03-offline-voice-journal/transcribe.py`
- [Journal Summary](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/03-offline-voice-journal/summary.py): `vol-3/03-offline-voice-journal/summary.py`
- [Life Dashboard](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/04-ambient-life-dashboard/server.py): `vol-3/04-ambient-life-dashboard/server.py`
- [Decision Simulator](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-3/05-decision-simulator/simulate.py): `vol-3/05-decision-simulator/simulate.py`

### Personal Data

- [Writing Ingest](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/01-past-you-searcher/ingest.py): `vol-4/01-past-you-searcher/ingest.py`
- [Past-You Search](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/01-past-you-searcher/ask.py): `vol-4/01-past-you-searcher/ask.py`
- [Photo Timeline](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/02-pattern-mirror/analyze.py): `vol-4/02-pattern-mirror/analyze.py`
- [Photo Analysis](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/02-pattern-mirror/photolib.py): `vol-4/02-pattern-mirror/photolib.py`
- [Lookout](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/03-lookout/check.py): `vol-4/03-lookout/check.py`
- [Personal API](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/04-personal-api/server.py): `vol-4/04-personal-api/server.py`
- [Freedom Calculator](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-4/05-freedom-calculator/simulate.py): `vol-4/05-freedom-calculator/simulate.py`

### Vol 5 Projects

- [Content Brain](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/content_brain.py): `vol-5/01-content-brain/content_brain.py`
- [Content Q&A](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/ask.py): `vol-5/01-content-brain/ask.py`
- [Content Board](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/01-content-brain/build_board.py): `vol-5/01-content-brain/build_board.py`
- [Context Assembly](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/02-context-layer/context.py): `vol-5/02-context-layer/context.py`
- [Corrections Memory](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/02-context-layer/memory.py): `vol-5/02-context-layer/memory.py`
- [Nutrition Lens](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/03-nutrition-lens/lens.py): `vol-5/03-nutrition-lens/lens.py`
- [Meal Rules](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/03-nutrition-lens/rules.py): `vol-5/03-nutrition-lens/rules.py`
- [Motion Studio](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/04-motion-studio/generate.py): `vol-5/04-motion-studio/generate.py`
- [Motion Rendering](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/04-motion-studio/render.py): `vol-5/04-motion-studio/render.py`
- [Game Environment](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/arena.py): `vol-5/05-the-arena/arena.py`
- [Q-Learning](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/train.py): `vol-5/05-the-arena/train.py`
- [Agent Replay](https://github.com/kju4q/ai-weekend-builds/blob/main/vol-5/05-the-arena/watch.py): `vol-5/05-the-arena/watch.py`

### Other components

- **User**

## Connections

- User → Personal RAG: asks about documents (evidence: `README.md`)
- User → Research Crew: requests research (evidence: `README.md`)
- User → Coding Agent: provides issue (evidence: `README.md`)
- User → Document Ingest: adds documents (evidence: `README.md`)
- User → Document Q&A: asks questions (evidence: `README.md`)
- User → Money Map: provides bank CSV (evidence: `README.md`)
- User → Voice Recording: records voice (evidence: `README.md`)
- User → Life Dashboard: views daily scene (evidence: `README.md`)
- User → Decision Simulator: simulates decision (evidence: `README.md`)
- User → Writing Ingest: indexes writing (evidence: `README.md`)
- User → Past-You Search: searches memories (evidence: `README.md`)
- User → Photo Timeline: analyzes photos (evidence: `README.md`)
- User → Lookout: sets watched sources (evidence: `README.md`)
- User → Personal API: uses personal endpoints (evidence: `README.md`)
- User → Freedom Calculator: sets assumptions (evidence: `README.md`)
- User → Content Board: files content (evidence: `README.md`)
- User → Context Assembly: assembles context (evidence: `README.md`)
- User → Nutrition Lens: provides meal (evidence: `README.md`)
- User → Motion Studio: generates motion (evidence: `README.md`)
- User → Q-Learning: trains agent (evidence: `README.md`)
- User → Game Environment: plays game (evidence: `README.md`)
- Document Ingest → Local Embeddings: uses embeddings (evidence: `vol-3/01-life-admin-brain/ingest.py`)
- Document Q&A → Local Embeddings: uses embeddings (evidence: `vol-3/01-life-admin-brain/ask.py`)
- Writing Ingest → Local Embeddings: uses embeddings (evidence: `vol-4/01-past-you-searcher/ingest.py`)
- Photo Timeline → Photo Analysis: delegates analysis (evidence: `vol-4/02-pattern-mirror/analyze.py`)
- Content Q&A → Content Brain: imports shared logic (evidence: `vol-5/01-content-brain/ask.py`)
- Content Board → Content Brain: imports shared logic (evidence: `vol-5/01-content-brain/build_board.py`)
- Context Assembly → Corrections Memory: reads corrections (evidence: `vol-5/02-context-layer/context.py`)
- Nutrition Lens → Meal Rules: uses meal rules (evidence: `vol-5/03-nutrition-lens/lens.py`)
- Q-Learning → Game Environment: trains in environment (evidence: `vol-5/05-the-arena/train.py`)
- Agent Replay → Game Environment: uses environment (evidence: `vol-5/05-the-arena/watch.py`)
- Agent Replay → Q-Learning: loads training output (evidence: `vol-5/05-the-arena/watch.py`)
