# jakewan/overstory architecture

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

- Interactive diagram: https://gitdiagram.com/jakewan/overstory
- Repository: https://github.com/jakewan/overstory

## Overview

Overstory is a manifest-driven GitHub project-management MCP server: an MCP client requests structured project facts, the server resolves repository conventions, fetches GitHub data, and computes reductions for the caller to render. Its major reads cover backlog grooming, project orientation, milestone tracks, authored activity, and maintenance activity, including batch variants. The excerpts show concrete project-summary and milestone-track orchestration; the source index identifies other server integrations but does not expose their handler bodies, so those links are limited to indexed evidence.

Main entry points: [`internal/server/server.go`](https://github.com/jakewan/overstory/blob/main/internal/server/server.go) (Tool Server), [`internal/server/project_summary.go`](https://github.com/jakewan/overstory/blob/main/internal/server/project_summary.go) (Project Summary), [`internal/github/graphql.go`](https://github.com/jakewan/overstory/blob/main/internal/github/graphql.go) (GraphQL Fetcher), [`internal/backlog/deferred.go`](https://github.com/jakewan/overstory/blob/main/internal/backlog/deferred.go) (Backlog Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_entry["stdio Entrypoint<br/>[main.go]"]
  node_server["Tool Server<br/>[server.go]"]
end

subgraph group_config["Repository Conventions"]
  node_manifest["Manifest Resolver<br/>[manifest.go]"]
end

subgraph group_github["GitHub Data"]
  node_ghfetch["GraphQL Fetcher<br/>[graphql.go]"]
end

subgraph group_analysis["Project Analysis"]
  node_project["Project Summary<br/>[project_summary.go]"]
  node_milestone["Milestone Tracks"]
  node_backlog["Backlog Review<br/>[deferred.go]"]
  node_critical["Critical Path<br/>[criticalpath.go]"]
  node_dependency["Dependency Analysis<br/>[dependency.go]"]
  node_summary["Summary Reductions<br/>[recommendations.go]"]
  node_trackparse["Track Parser<br/>[milestonetracks.go]"]
  node_authored["Authored Activity<br/>[authored.go]"]
  node_maintenance["Maintenance Activity<br/>[maintenance.go]"]
  node_reduce["Shared Reductions<br/>[issuerefs.go]"]
end

node_client(("MCP Client"))
node_githubapi{{"GitHub API"}}

node_client -->|"calls over stdio"| node_entry
node_entry -->|"constructs server"| node_server
node_server -->|"serves MCP tools"| node_client
node_server -->|"resolves conventions"| node_manifest
node_server -->|"fetches repository data"| node_ghfetch
node_ghfetch -.->|"queries GraphQL"| node_githubapi
node_project -->|"resolves configuration"| node_manifest
node_project -->|"fetches issues"| node_ghfetch
node_project -->|"computes summary"| node_summary
node_project -->|"classifies dependencies"| node_dependency
node_project -->|"projects issue set"| node_reduce
node_milestone -->|"resolves conventions"| node_manifest
node_milestone -->|"fetches milestones"| node_ghfetch
node_milestone -->|"reduces track descriptions"| node_trackparse
node_server -->|"registers backlog review"| node_backlog
node_backlog -->|"uses gate reduction"| node_critical
node_backlog -->|"uses dependency reduction"| node_dependency
node_backlog -->|"uses shared projections"| node_reduce
node_server -->|"registers authored reads"| node_authored
node_server -->|"registers maintenance reads"| node_maintenance
node_authored -->|"uses rate-limit facts"| node_reduce
node_maintenance -.->|"consumes fetched events"| node_ghfetch

click node_entry "https://github.com/jakewan/overstory/blob/main/cmd/overstory/main.go"
click node_server "https://github.com/jakewan/overstory/blob/main/internal/server/server.go"
click node_manifest "https://github.com/jakewan/overstory/blob/main/internal/manifest/manifest.go"
click node_ghfetch "https://github.com/jakewan/overstory/blob/main/internal/github/graphql.go"
click node_project "https://github.com/jakewan/overstory/blob/main/internal/server/project_summary.go"
click node_milestone "https://github.com/jakewan/overstory/blob/main/internal/server/milestone_tracks.go"
click node_backlog "https://github.com/jakewan/overstory/blob/main/internal/backlog/deferred.go"
click node_critical "https://github.com/jakewan/overstory/blob/main/internal/criticalpath/criticalpath.go"
click node_dependency "https://github.com/jakewan/overstory/blob/main/internal/dependency/dependency.go"
click node_summary "https://github.com/jakewan/overstory/blob/main/internal/summary/recommendations.go"
click node_trackparse "https://github.com/jakewan/overstory/blob/main/internal/summary/milestonetracks.go"
click node_authored "https://github.com/jakewan/overstory/blob/main/internal/authored/authored.go"
click node_maintenance "https://github.com/jakewan/overstory/blob/main/internal/maintenance/maintenance.go"
click node_reduce "https://github.com/jakewan/overstory/blob/main/internal/reduce/issuerefs.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_entry,node_server,node_client toneBlue
class node_manifest toneAmber
class node_ghfetch,node_githubapi toneMint
class node_project,node_milestone,node_backlog,node_critical,node_dependency,node_summary,node_trackparse,node_authored,node_maintenance,node_reduce toneRose
```

## Components

### MCP Runtime

- [stdio Entrypoint](https://github.com/jakewan/overstory/blob/main/cmd/overstory/main.go): `cmd/overstory/main.go`
- [Tool Server](https://github.com/jakewan/overstory/blob/main/internal/server/server.go): `internal/server/server.go`

### Repository Conventions

- [Manifest Resolver](https://github.com/jakewan/overstory/blob/main/internal/manifest/manifest.go): `internal/manifest/manifest.go`

### GitHub Data

- [GraphQL Fetcher](https://github.com/jakewan/overstory/blob/main/internal/github/graphql.go): `internal/github/graphql.go`

### Project Analysis

- [Project Summary](https://github.com/jakewan/overstory/blob/main/internal/server/project_summary.go): `internal/server/project_summary.go`
- [Milestone Tracks](https://github.com/jakewan/overstory/blob/main/internal/server/milestone_tracks.go): `internal/server/milestone_tracks.go`
- [Backlog Review](https://github.com/jakewan/overstory/blob/main/internal/backlog/deferred.go): `internal/backlog/deferred.go`
- [Critical Path](https://github.com/jakewan/overstory/blob/main/internal/criticalpath/criticalpath.go): `internal/criticalpath/criticalpath.go`
- [Dependency Analysis](https://github.com/jakewan/overstory/blob/main/internal/dependency/dependency.go): `internal/dependency/dependency.go`
- [Summary Reductions](https://github.com/jakewan/overstory/blob/main/internal/summary/recommendations.go): `internal/summary/recommendations.go`
- [Track Parser](https://github.com/jakewan/overstory/blob/main/internal/summary/milestonetracks.go): `internal/summary/milestonetracks.go`
- [Authored Activity](https://github.com/jakewan/overstory/blob/main/internal/authored/authored.go): `internal/authored/authored.go`
- [Maintenance Activity](https://github.com/jakewan/overstory/blob/main/internal/maintenance/maintenance.go): `internal/maintenance/maintenance.go`
- [Shared Reductions](https://github.com/jakewan/overstory/blob/main/internal/reduce/issuerefs.go): `internal/reduce/issuerefs.go`

### Other components

- **MCP Client**
- **GitHub API**

## Connections

- MCP Client → stdio Entrypoint: calls over stdio (evidence: `cmd/overstory/main.go`)
- stdio Entrypoint → Tool Server: constructs server (evidence: `cmd/overstory/main.go`)
- Tool Server → MCP Client: serves MCP tools
- Tool Server → Manifest Resolver: resolves conventions
- Tool Server → GraphQL Fetcher: fetches repository data (evidence: `internal/server/server.go`)
- GraphQL Fetcher → GitHub API: queries GraphQL (evidence: `README.md`)
- Project Summary → Manifest Resolver: resolves configuration (evidence: `internal/server/project_summary.go`)
- Project Summary → GraphQL Fetcher: fetches issues (evidence: `internal/server/project_summary.go`)
- Project Summary → Summary Reductions: computes summary (evidence: `internal/server/project_summary.go`)
- Project Summary → Dependency Analysis: classifies dependencies (evidence: `internal/server/project_summary.go`)
- Project Summary → Shared Reductions: projects issue set (evidence: `internal/server/project_summary.go`)
- Milestone Tracks → Manifest Resolver: resolves conventions (evidence: `internal/server/milestone_tracks.go`)
- Milestone Tracks → GraphQL Fetcher: fetches milestones (evidence: `internal/server/milestone_tracks.go`)
- Milestone Tracks → Track Parser: reduces track descriptions (evidence: `internal/server/milestone_tracks.go`)
- Tool Server → Backlog Review: registers backlog review (evidence: `internal/server/server.go`)
- Backlog Review → Critical Path: uses gate reduction (evidence: `internal/backlog/deferred.go`)
- Backlog Review → Dependency Analysis: uses dependency reduction (evidence: `internal/backlog/deferred.go`)
- Backlog Review → Shared Reductions: uses shared projections (evidence: `internal/backlog/deferred.go`)
- Tool Server → Authored Activity: registers authored reads (evidence: `internal/server/server.go`)
- Tool Server → Maintenance Activity: registers maintenance reads (evidence: `internal/server/server.go`)
- Authored Activity → Shared Reductions: uses rate-limit facts (evidence: `internal/authored/authored.go`)
- Maintenance Activity → GraphQL Fetcher: consumes fetched events