# coleam00/ai-software-factory architecture

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

- Interactive diagram: https://gitdiagram.com/coleam00/ai-software-factory
- Repository: https://github.com/coleam00/ai-software-factory

## Overview

AI Software Factory installs project-specific context and runtime support, then delegates AI work to Archon’s shared SDLC workflows. The principal loop starts with a human’s release plan, proceeds through issue intake, implementation and independent review, and reaches staging for customer-like validation; defects return as new issues. The repository also supports scheduling and loop health, merge/deployment controls, and isolated runtime verification. Archon’s workflow internals are external to this repository, so those capabilities are represented as an external subsystem and linked where the README documents the relationship.

Main entry points: [`template/factory/consumer.py`](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py) (Archon consumer), [`bin/install.py`](https://github.com/coleam00/ai-software-factory/blob/main/bin/install.py) (Project installer), [`template/harness`](https://github.com/coleam00/ai-software-factory/tree/main/template/harness) (Staging use), [`bin/factory.py`](https://github.com/coleam00/ai-software-factory/blob/main/bin/factory.py) (Factory CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and context"]
  node_factory_cli["Factory CLI<br/>[factory.py]"]
  node_installer["Project installer<br/>[install.py]"]
  node_project_context["Project context"]
end

subgraph group_workflow["Release workflow"]
  node_consumer["Archon consumer<br/>[consumer.py]"]
  node_archon["Archon SDLC pack"]
  node_issue_intake["Issue intake<br/>[consumer.py]"]
  node_implementation["Issue implementation<br/>[consumer.py]"]
  node_review_merge["Review and merge<br/>[consumer.py]"]
end

subgraph group_validation["Validation runtime"]
  node_staging["Staging use"]
  node_harness_driver["App harness<br/>[appproc.py]"]
  node_runtime_resource["Revision resource"]
  node_runtime_host["Runtime host<br/>[runtime_host.py]"]
  node_process_owner["Process ownership<br/>[runtime_process.py]"]
  node_holdout_fence["Holdout fence<br/>[holdout_fence.py]"]
end

subgraph group_operations["Loop operations"]
  node_scheduler["Lap scheduler<br/>[consumer.py]"]
  node_manager["Loop manager<br/>[consumer.py]"]
  node_deployment["Deterministic deployment<br/>[consumer.py]"]
end

node_planner(("Product planner"))
node_customer(("Staging customer"))

node_planner -->|"starts setup"| node_factory_cli
node_factory_cli -->|"installs project"| node_installer
node_installer -->|"installs templates"| node_project_context
node_installer -->|"configures integration"| node_consumer
node_project_context -->|"supplies project context"| node_archon
node_planner -->|"defines release"| node_issue_intake
node_issue_intake -->|"routes workflow"| node_archon
node_archon -->|"assigns issue"| node_implementation
node_implementation -->|"submits work"| node_archon
node_archon -->|"routes review"| node_review_merge
node_review_merge -->|"merges to staging"| node_staging
node_customer -->|"uses release"| node_staging
node_customer -->|"reports defects"| node_issue_intake
node_staging -->|"validates app"| node_harness_driver
node_runtime_resource -->|"provides resource root"| node_runtime_host
node_runtime_host -->|"owns app processes"| node_process_owner
node_consumer -->|"invokes pinned source"| node_archon
node_consumer -->|"launches laps"| node_scheduler
node_scheduler -->|"starts workflow runs"| node_archon
node_consumer -->|"manages loop health"| node_manager
node_archon -->|"routes deployment"| node_deployment
node_review_merge -.->|"uses holdout protection"| node_holdout_fence

click node_factory_cli "https://github.com/coleam00/ai-software-factory/blob/main/bin/factory.py"
click node_installer "https://github.com/coleam00/ai-software-factory/blob/main/bin/install.py"
click node_project_context "https://github.com/coleam00/ai-software-factory/tree/main/template"
click node_consumer "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_issue_intake "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_implementation "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_review_merge "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_staging "https://github.com/coleam00/ai-software-factory/tree/main/template/harness"
click node_harness_driver "https://github.com/coleam00/ai-software-factory/blob/main/template/harness/appproc.py"
click node_runtime_resource "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_resource.py"
click node_runtime_host "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_host.py"
click node_process_owner "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_process.py"
click node_holdout_fence "https://github.com/coleam00/ai-software-factory/blob/main/template/.factory/hooks/holdout_fence.py"
click node_scheduler "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_manager "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py"
click node_deployment "https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.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_factory_cli,node_installer,node_project_context toneBlue
class node_consumer,node_archon,node_issue_intake,node_implementation,node_review_merge toneAmber
class node_staging,node_harness_driver,node_runtime_resource,node_runtime_host,node_process_owner,node_holdout_fence toneMint
class node_scheduler,node_manager,node_deployment toneRose
class node_planner,node_customer toneIndigo
```

## Components

### Setup and context

- [Factory CLI](https://github.com/coleam00/ai-software-factory/blob/main/bin/factory.py): `bin/factory.py`
- [Project installer](https://github.com/coleam00/ai-software-factory/blob/main/bin/install.py): `bin/install.py`
- [Project context](https://github.com/coleam00/ai-software-factory/tree/main/template): `template`

### Release workflow

- [Archon consumer](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`
- **Archon SDLC pack**
- [Issue intake](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`
- [Issue implementation](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`
- [Review and merge](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`

### Validation runtime

- [Staging use](https://github.com/coleam00/ai-software-factory/tree/main/template/harness): `template/harness`
- [App harness](https://github.com/coleam00/ai-software-factory/blob/main/template/harness/appproc.py): `template/harness/appproc.py`
- [Revision resource](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_resource.py): `template/factory/runtime_resource.py`
- [Runtime host](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_host.py): `template/factory/runtime_host.py`
- [Process ownership](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/runtime_process.py): `template/factory/runtime_process.py`
- [Holdout fence](https://github.com/coleam00/ai-software-factory/blob/main/template/.factory/hooks/holdout_fence.py): `template/.factory/hooks/holdout_fence.py`

### Loop operations

- [Lap scheduler](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`
- [Loop manager](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`
- [Deterministic deployment](https://github.com/coleam00/ai-software-factory/blob/main/template/factory/consumer.py): `template/factory/consumer.py`

### Other components

- **Product planner**
- **Staging customer**

## Connections

- Product planner → Factory CLI: starts setup (evidence: `README.md`)
- Factory CLI → Project installer: installs project (evidence: `bin/factory.py`)
- Project installer → Project context: installs templates (evidence: `bin/install.py`)
- Project installer → Archon consumer: configures integration (evidence: `bin/install.py`)
- Project context → Archon SDLC pack: supplies project context (evidence: `README.md`)
- Product planner → Issue intake: defines release (evidence: `README.md`)
- Issue intake → Archon SDLC pack: routes workflow (evidence: `README.md`)
- Archon SDLC pack → Issue implementation: assigns issue (evidence: `README.md`)
- Issue implementation → Archon SDLC pack: submits work (evidence: `README.md`)
- Archon SDLC pack → Review and merge: routes review (evidence: `README.md`)
- Review and merge → Staging use: merges to staging (evidence: `README.md`)
- Staging customer → Staging use: uses release (evidence: `README.md`)
- Staging customer → Issue intake: reports defects (evidence: `README.md`)
- Staging use → App harness: validates app (evidence: `README.md`)
- Revision resource → Runtime host: provides resource root (evidence: `template/factory/runtime_resource.py`)
- Runtime host → Process ownership: owns app processes (evidence: `template/factory/runtime_host.py`)
- Archon consumer → Archon SDLC pack: invokes pinned source (evidence: `template/factory/consumer.py`)
- Archon consumer → Lap scheduler: launches laps (evidence: `README.md`)
- Lap scheduler → Archon SDLC pack: starts workflow runs (evidence: `README.md`)
- Archon consumer → Loop manager: manages loop health (evidence: `README.md`)
- Archon SDLC pack → Deterministic deployment: routes deployment (evidence: `README.md`)
- Review and merge → Holdout fence: uses holdout protection (evidence: `README.md`)
