# snowby666/forge architecture

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

- Interactive diagram: https://gitdiagram.com/snowby666/forge
- Repository: https://github.com/snowby666/forge

## Overview

Forge is an autonomous hackathon system: it discovers and scores events, researches competitors, judges and sponsors, plans a project, builds and verifies it, then prepares and submits a demo and pitch. The Commander coordinates the agent workflow and human approval checkpoints; infrastructure agents preserve learning and monitor runs. A separate web dashboard manages runs and exposes live status. The README documents capabilities beyond the sampled excerpts, so unsampled stages are represented at their documented directory paths; uncertain internal call wiring is omitted.

Main entry points: [`agents/python/orchestrator/commander.py`](https://github.com/snowby666/forge/blob/main/agents/python/orchestrator/commander.py) (Commander), [`forge_web/routes`](https://github.com/snowby666/forge/tree/main/forge_web/routes) (Dashboard API), [`agents/browser/server.ts`](https://github.com/snowby666/forge/blob/main/agents/browser/server.ts) (Browser automation), [`agents/python/intelligence/hackathon_scout.py`](https://github.com/snowby666/forge/blob/main/agents/python/intelligence/hackathon_scout.py) (Scout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Hackathon workflow"]
  node_commander["Commander<br/>[commander.py]"]
  node_scout["Scout<br/>[hackathon_scout.py]"]
  node_checkpoints["Human checkpoints<br/>[commander.py]"]
  node_submission["Demo and submission"]
end

subgraph group_agents["Specialist agents"]
  node_intelligence["Project intelligence"]
  node_strategy["Strategy and planning"]
  node_build["Parallel project build<br/>[agents_config.py]"]
  node_verification["Quality verification<br/>[ux_auditor.py]"]
  node_polish["Project polish<br/>[polish_agents.py]"]
end

subgraph group_infra["Learning and operations"]
  node_memory[("Persistent memory<br/>[memory_keeper.py]")]
  node_outcomes["Outcome learning<br/>[outcome_tracker.py]"]
  node_knowledge["Knowledge updates"]
  node_monitor["Run monitoring"]
  node_redis[("Run state<br/>[redis_client.py]")]
end

subgraph group_dashboard["Web dashboard"]
  node_api["Dashboard API"]
  node_services["Dashboard services<br/>[services.py]"]
  node_frontend["Dashboard UI"]
end

subgraph group_integrations["External services"]
  node_browser["Browser automation<br/>[server.ts]"]
  node_hackathon_sites["Hackathon platforms"]
  node_llm["ElectronHub LLM"]
  node_submission_sites["Submission platforms"]
  node_calendar["Google Calendar"]
  node_web_search["Web search"]
end

node_organizer(("Hackathon organizer"))
node_human(("Human participant"))

node_organizer -->|"requests discovery"| node_scout
node_scout -->|"scrapes listings"| node_browser
node_browser -->|"reads event data"| node_hackathon_sites
node_scout -->|"registers opportunities"| node_commander
node_commander -->|"dispatches research"| node_intelligence
node_commander -->|"dispatches planning"| node_strategy
node_intelligence -->|"analyzes evidence"| node_llm
node_strategy -->|"generates plans"| node_llm
node_commander -->|"coordinates approvals"| node_checkpoints
node_checkpoints -->|"requests decisions"| node_human
node_human -->|"approves stages"| node_checkpoints
node_commander -->|"dispatches build"| node_build
node_commander -->|"dispatches audits"| node_verification
node_commander -->|"dispatches polish"| node_polish
node_commander -->|"dispatches submission"| node_submission
node_verification -->|"requests screenshots"| node_browser
node_submission -->|"records demo"| node_browser
node_submission -->|"submits entry"| node_submission_sites
node_commander -->|"reads and writes state"| node_redis
node_intelligence -->|"learns from prior runs"| node_memory
node_outcomes -->|"feeds results"| node_memory
node_knowledge -->|"researches trends"| node_web_search
node_knowledge -->|"updates design knowledge"| node_strategy
node_monitor -->|"schedules checkpoints"| node_calendar
node_frontend -->|"calls dashboard API"| node_api
node_api -->|"uses services"| node_services
node_services -->|"reads and writes state"| node_redis
node_api -->|"launches runs"| node_commander
node_api -->|"serves approvals"| node_human
node_commander -->|"tracks run activity"| node_monitor

click node_commander "https://github.com/snowby666/forge/blob/main/agents/python/orchestrator/commander.py"
click node_scout "https://github.com/snowby666/forge/blob/main/agents/python/intelligence/hackathon_scout.py"
click node_intelligence "https://github.com/snowby666/forge/tree/main/agents/python/intelligence"
click node_strategy "https://github.com/snowby666/forge/tree/main/agents/python/strategy"
click node_checkpoints "https://github.com/snowby666/forge/blob/main/agents/python/orchestrator/commander.py"
click node_build "https://github.com/snowby666/forge/blob/main/config/agents_config.py"
click node_verification "https://github.com/snowby666/forge/blob/main/agents/python/verify/ux_auditor.py"
click node_polish "https://github.com/snowby666/forge/blob/main/agents/python/polish/polish_agents.py"
click node_submission "https://github.com/snowby666/forge/blob/main/agents/python/submission/submission_pipeline.py"
click node_memory "https://github.com/snowby666/forge/blob/main/agents/python/infra/memory_keeper.py"
click node_outcomes "https://github.com/snowby666/forge/blob/main/agents/python/infra/outcome_tracker.py"
click node_knowledge "https://github.com/snowby666/forge/blob/main/agents/python/infra/knowledge_updater.py"
click node_monitor "https://github.com/snowby666/forge/blob/main/agents/python/infra/monitor_and_calendar.py"
click node_redis "https://github.com/snowby666/forge/blob/main/config/redis_client.py"
click node_api "https://github.com/snowby666/forge/tree/main/forge_web/routes"
click node_services "https://github.com/snowby666/forge/blob/main/forge_web/services.py"
click node_frontend "https://github.com/snowby666/forge/tree/main/web/src/app/(dashboard)"
click node_browser "https://github.com/snowby666/forge/blob/main/agents/browser/server.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_commander,node_scout,node_checkpoints,node_submission toneBlue
class node_intelligence,node_strategy,node_build,node_verification,node_polish toneAmber
class node_memory,node_outcomes,node_knowledge,node_monitor,node_redis toneMint
class node_api,node_services,node_frontend toneRose
class node_browser,node_hackathon_sites,node_llm,node_submission_sites,node_calendar,node_web_search,node_organizer,node_human toneIndigo
```

## Components

### Hackathon workflow

- [Commander](https://github.com/snowby666/forge/blob/main/agents/python/orchestrator/commander.py): `agents/python/orchestrator/commander.py`
- [Scout](https://github.com/snowby666/forge/blob/main/agents/python/intelligence/hackathon_scout.py): `agents/python/intelligence/hackathon_scout.py`
- [Human checkpoints](https://github.com/snowby666/forge/blob/main/agents/python/orchestrator/commander.py): `agents/python/orchestrator/commander.py`
- [Demo and submission](https://github.com/snowby666/forge/blob/main/agents/python/submission/submission_pipeline.py): `agents/python/submission/submission_pipeline.py`

### Specialist agents

- [Project intelligence](https://github.com/snowby666/forge/tree/main/agents/python/intelligence): `agents/python/intelligence`
- [Strategy and planning](https://github.com/snowby666/forge/tree/main/agents/python/strategy): `agents/python/strategy`
- [Parallel project build](https://github.com/snowby666/forge/blob/main/config/agents_config.py): `config/agents_config.py`
- [Quality verification](https://github.com/snowby666/forge/blob/main/agents/python/verify/ux_auditor.py): `agents/python/verify/ux_auditor.py`
- [Project polish](https://github.com/snowby666/forge/blob/main/agents/python/polish/polish_agents.py): `agents/python/polish/polish_agents.py`

### Learning and operations

- [Persistent memory](https://github.com/snowby666/forge/blob/main/agents/python/infra/memory_keeper.py): `agents/python/infra/memory_keeper.py`
- [Outcome learning](https://github.com/snowby666/forge/blob/main/agents/python/infra/outcome_tracker.py): `agents/python/infra/outcome_tracker.py`
- [Knowledge updates](https://github.com/snowby666/forge/blob/main/agents/python/infra/knowledge_updater.py): `agents/python/infra/knowledge_updater.py`
- [Run monitoring](https://github.com/snowby666/forge/blob/main/agents/python/infra/monitor_and_calendar.py): `agents/python/infra/monitor_and_calendar.py`
- [Run state](https://github.com/snowby666/forge/blob/main/config/redis_client.py): `config/redis_client.py`

### Web dashboard

- [Dashboard API](https://github.com/snowby666/forge/tree/main/forge_web/routes): `forge_web/routes`
- [Dashboard services](https://github.com/snowby666/forge/blob/main/forge_web/services.py): `forge_web/services.py`
- [Dashboard UI](https://github.com/snowby666/forge/tree/main/web/src/app/(dashboard)): `web/src/app/(dashboard)`

### External services

- [Browser automation](https://github.com/snowby666/forge/blob/main/agents/browser/server.ts): `agents/browser/server.ts`
- **Hackathon platforms**
- **ElectronHub LLM**
- **Submission platforms**
- **Google Calendar**
- **Web search**

### Other components

- **Hackathon organizer**
- **Human participant**

## Connections

- Hackathon organizer → Scout: requests discovery
- Scout → Browser automation: scrapes listings
- Browser automation → Hackathon platforms: reads event data
- Scout → Commander: registers opportunities
- Commander → Project intelligence: dispatches research
- Commander → Strategy and planning: dispatches planning
- Project intelligence → ElectronHub LLM: analyzes evidence
- Strategy and planning → ElectronHub LLM: generates plans
- Commander → Human checkpoints: coordinates approvals
- Human checkpoints → Human participant: requests decisions
- Human participant → Human checkpoints: approves stages
- Commander → Parallel project build: dispatches build
- Commander → Quality verification: dispatches audits
- Commander → Project polish: dispatches polish
- Commander → Demo and submission: dispatches submission
- Quality verification → Browser automation: requests screenshots
- Demo and submission → Browser automation: records demo
- Demo and submission → Submission platforms: submits entry
- Commander → Run state: reads and writes state
- Project intelligence → Persistent memory: learns from prior runs
- Outcome learning → Persistent memory: feeds results
- Knowledge updates → Web search: researches trends
- Knowledge updates → Strategy and planning: updates design knowledge
- Run monitoring → Google Calendar: schedules checkpoints
- Dashboard UI → Dashboard API: calls dashboard API
- Dashboard API → Dashboard services: uses services
- Dashboard services → Run state: reads and writes state
- Dashboard API → Commander: launches runs
- Dashboard API → Human participant: serves approvals
- Commander → Run monitoring: tracks run activity