# kinncj/maple architecture

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

- Interactive diagram: https://gitdiagram.com/kinncj/maple
- Repository: https://github.com/kinncj/maple

## Overview

MAPLE is a local-first Go application for orchestrating AI coding harnesses through an artifact-driven, phase-gated development lifecycle. The user initializes a project, captures requirements as Gherkin stories, then works from a dashboard that presents project activity and launches a harness; UI stories can pause for design review and approval in the built-in portal. The graph also includes template setup, GitHub support, and the state layer. Source excerpts are partial, so some documented capabilities are shown without speculative internal call chains.

Main entry points: [`app/cmd/maple/main.go`](https://github.com/kinncj/maple/blob/main/app/cmd/maple/main.go) (Maple CLI), [`app/internal/tui/dashboard/model.go`](https://github.com/kinncj/maple/blob/main/app/internal/tui/dashboard/model.go) (Project dashboard), [`app/internal/tui/req/ui.go`](https://github.com/kinncj/maple/blob/main/app/internal/tui/req/ui.go) (Requirements UI), [`app/internal/portal/portal.go`](https://github.com/kinncj/maple/blob/main/app/internal/portal/portal.go) (Review server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Setup"]
  node_cli["Maple CLI<br/>[main.go]"]
  node_setup_menu["Setup menu<br/>[menu.go]"]
  node_scaffold["Project scaffolding<br/>[scaffold.go]"]
  node_template["Embedded template<br/>[embed.go]"]
end

subgraph group_workflow["Requirements and Harness"]
  node_requirements_ui["Requirements UI<br/>[ui.go]"]
  node_requirements_launch["Harness handoff<br/>[launch.go]"]
  node_requirements_parse["Requirement parsing<br/>[parse.go]"]
  node_requirements_convert["Gherkin conversion<br/>[convert.go]"]
  node_requirements_save["Story persistence<br/>[save.go]"]
  node_harness["AI harnesses<br/>[harness.go]"]
end

subgraph group_dashboard["Dashboard and State"]
  node_dashboard_ui["Project dashboard<br/>[model.go]"]
  node_dashboard_sources["Dashboard views<br/>[sources.go]"]
  node_pane["Focus and scroll panes<br/>[pane.go]"]
  node_state[("Project state")]
  node_github["GitHub integration<br/>[gh.go]"]
end

subgraph group_review["Design Review Portal"]
  node_portal_server["Review server<br/>[portal.go]"]
  node_portal_artifacts["Artifact discovery<br/>[artifacts.go]"]
  node_portal_actions["Review actions<br/>[actions.go]"]
end

node_user(("Project developer"))
node_reviewer(("Human reviewer"))
node_browser["Browser"]

node_user -->|"runs"| node_cli
node_cli -->|"offers setup"| node_setup_menu
node_cli -->|"initializes project"| node_scaffold
node_scaffold -.->|"scaffolds from"| node_template
node_cli -->|"runs requirements"| node_requirements_ui
node_requirements_ui -->|"converts input"| node_requirements_parse
node_requirements_ui -->|"creates stories"| node_requirements_convert
node_requirements_ui -.->|"saves stories"| node_requirements_save
node_requirements_ui -->|"starts handoff"| node_requirements_launch
node_requirements_launch -->|"launches in pane"| node_harness
node_cli -->|"runs dashboard"| node_dashboard_ui
node_dashboard_ui -->|"builds views"| node_dashboard_sources
node_dashboard_ui -->|"composes panes"| node_pane
node_dashboard_ui -->|"reads project data"| node_state
node_dashboard_ui -.->|"launches harness"| node_harness
node_dashboard_ui -.->|"refreshes GitHub data"| node_github
node_cli -.->|"supports GitHub actions"| node_github
node_cli -->|"starts review portal"| node_portal_server
node_portal_server -->|"serves artifacts"| node_portal_artifacts
node_portal_artifacts -->|"reads stories"| node_state
node_reviewer -->|"reviews design"| node_browser
node_browser -->|"opens portal"| node_portal_server
node_reviewer -.->|"approves gate"| node_portal_actions
node_portal_actions -->|"nudges to resume"| node_harness

click node_cli "https://github.com/kinncj/maple/blob/main/app/cmd/maple/main.go"
click node_setup_menu "https://github.com/kinncj/maple/blob/main/app/internal/tui/menu/menu.go"
click node_scaffold "https://github.com/kinncj/maple/blob/main/app/internal/scaffold/scaffold.go"
click node_template "https://github.com/kinncj/maple/blob/main/app/cmd/maple/embed.go"
click node_requirements_ui "https://github.com/kinncj/maple/blob/main/app/internal/tui/req/ui.go"
click node_requirements_launch "https://github.com/kinncj/maple/blob/main/app/internal/tui/req/launch.go"
click node_requirements_parse "https://github.com/kinncj/maple/blob/main/app/internal/req/parse.go"
click node_requirements_convert "https://github.com/kinncj/maple/blob/main/app/internal/req/convert.go"
click node_requirements_save "https://github.com/kinncj/maple/blob/main/app/internal/req/save.go"
click node_harness "https://github.com/kinncj/maple/blob/main/app/internal/harness/harness.go"
click node_dashboard_ui "https://github.com/kinncj/maple/blob/main/app/internal/tui/dashboard/model.go"
click node_dashboard_sources "https://github.com/kinncj/maple/blob/main/app/internal/tui/dashboard/sources.go"
click node_pane "https://github.com/kinncj/maple/blob/main/app/internal/tui/pane/pane.go"
click node_state "https://github.com/kinncj/maple/tree/main/app/internal/state"
click node_github "https://github.com/kinncj/maple/blob/main/app/internal/gh/gh.go"
click node_portal_server "https://github.com/kinncj/maple/blob/main/app/internal/portal/portal.go"
click node_portal_artifacts "https://github.com/kinncj/maple/blob/main/app/internal/portal/artifacts.go"
click node_portal_actions "https://github.com/kinncj/maple/blob/main/app/internal/portal/actions.go"

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_cli,node_setup_menu,node_scaffold,node_template,node_reviewer,node_browser toneBlue
class node_requirements_ui,node_requirements_launch,node_requirements_parse,node_requirements_convert,node_requirements_save,node_harness toneAmber
class node_dashboard_ui,node_dashboard_sources,node_pane,node_state,node_github toneMint
class node_portal_server,node_portal_artifacts,node_portal_actions toneRose
class node_user toneIndigo
```

## Components

### CLI and Setup

- [Maple CLI](https://github.com/kinncj/maple/blob/main/app/cmd/maple/main.go): `app/cmd/maple/main.go`
- [Setup menu](https://github.com/kinncj/maple/blob/main/app/internal/tui/menu/menu.go): `app/internal/tui/menu/menu.go`
- [Project scaffolding](https://github.com/kinncj/maple/blob/main/app/internal/scaffold/scaffold.go): `app/internal/scaffold/scaffold.go`
- [Embedded template](https://github.com/kinncj/maple/blob/main/app/cmd/maple/embed.go): `app/cmd/maple/embed.go`

### Requirements and Harness

- [Requirements UI](https://github.com/kinncj/maple/blob/main/app/internal/tui/req/ui.go): `app/internal/tui/req/ui.go`
- [Harness handoff](https://github.com/kinncj/maple/blob/main/app/internal/tui/req/launch.go): `app/internal/tui/req/launch.go`
- [Requirement parsing](https://github.com/kinncj/maple/blob/main/app/internal/req/parse.go): `app/internal/req/parse.go`
- [Gherkin conversion](https://github.com/kinncj/maple/blob/main/app/internal/req/convert.go): `app/internal/req/convert.go`
- [Story persistence](https://github.com/kinncj/maple/blob/main/app/internal/req/save.go): `app/internal/req/save.go`
- [AI harnesses](https://github.com/kinncj/maple/blob/main/app/internal/harness/harness.go): `app/internal/harness/harness.go`

### Dashboard and State

- [Project dashboard](https://github.com/kinncj/maple/blob/main/app/internal/tui/dashboard/model.go): `app/internal/tui/dashboard/model.go`
- [Dashboard views](https://github.com/kinncj/maple/blob/main/app/internal/tui/dashboard/sources.go): `app/internal/tui/dashboard/sources.go`
- [Focus and scroll panes](https://github.com/kinncj/maple/blob/main/app/internal/tui/pane/pane.go): `app/internal/tui/pane/pane.go`
- [Project state](https://github.com/kinncj/maple/tree/main/app/internal/state): `app/internal/state`
- [GitHub integration](https://github.com/kinncj/maple/blob/main/app/internal/gh/gh.go): `app/internal/gh/gh.go`

### Design Review Portal

- [Review server](https://github.com/kinncj/maple/blob/main/app/internal/portal/portal.go): `app/internal/portal/portal.go`
- [Artifact discovery](https://github.com/kinncj/maple/blob/main/app/internal/portal/artifacts.go): `app/internal/portal/artifacts.go`
- [Review actions](https://github.com/kinncj/maple/blob/main/app/internal/portal/actions.go): `app/internal/portal/actions.go`

### Other components

- **Project developer**
- **Human reviewer**
- **Browser**

## Connections

- Project developer → Maple CLI: runs
- Maple CLI → Setup menu: offers setup (evidence: `app/cmd/maple/main.go`)
- Maple CLI → Project scaffolding: initializes project (evidence: `app/cmd/maple/main.go`)
- Project scaffolding → Embedded template: scaffolds from
- Maple CLI → Requirements UI: runs requirements (evidence: `app/cmd/maple/main.go`)
- Requirements UI → Requirement parsing: converts input (evidence: `app/internal/tui/req/ui.go`)
- Requirements UI → Gherkin conversion: creates stories (evidence: `app/internal/tui/req/ui.go`)
- Requirements UI → Story persistence: saves stories
- Requirements UI → Harness handoff: starts handoff (evidence: `app/internal/tui/req/ui.go`)
- Harness handoff → AI harnesses: launches in pane
- Maple CLI → Project dashboard: runs dashboard (evidence: `app/cmd/maple/main.go`)
- Project dashboard → Dashboard views: builds views (evidence: `app/internal/tui/dashboard/model.go`)
- Project dashboard → Focus and scroll panes: composes panes (evidence: `app/internal/tui/dashboard/model.go`)
- Project dashboard → Project state: reads project data (evidence: `app/internal/tui/dashboard/model.go`)
- Project dashboard → AI harnesses: launches harness
- Project dashboard → GitHub integration: refreshes GitHub data
- Maple CLI → GitHub integration: supports GitHub actions
- Maple CLI → Review server: starts review portal (evidence: `app/cmd/maple/main.go`)
- Review server → Artifact discovery: serves artifacts (evidence: `app/internal/portal/portal.go`)
- Artifact discovery → Project state: reads stories (evidence: `app/internal/portal/artifacts.go`)
- Human reviewer → Browser: reviews design
- Browser → Review server: opens portal
- Human reviewer → Review actions: approves gate
- Review actions → AI harnesses: nudges to resume (evidence: `app/internal/portal/actions.go`)