# marcus/nightshift architecture

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

- Interactive diagram: https://gitdiagram.com/marcus/nightshift
- Repository: https://github.com/marcus/nightshift

## Overview

Nightshift is a Go CLI for scheduled, budget-aware AI maintenance of configured repositories, with changes delivered as branches or PRs. The principal workflow is configure projects and providers, preview eligible work, select tasks within budget and cooldown constraints, execute an agent plan/implement/review loop, then report results without writing to the primary branch. The map also preserves setup, security, integrations, and run-history capabilities. Preview and orchestration excerpts support some links; where command wiring was not sampled, workflow links are documented at the product level rather than asserted as specific calls.

Main entry points: [`cmd/nightshift/commands`](https://github.com/marcus/nightshift/tree/main/cmd/nightshift/commands) (CLI commands), [`internal/orchestrator/orchestrator.go`](https://github.com/marcus/nightshift/blob/main/internal/orchestrator/orchestrator.go) (Run orchestrator), [`internal/db/db.go`](https://github.com/marcus/nightshift/blob/main/internal/db/db.go) (SQLite database), [`internal/integrations/integrations.go`](https://github.com/marcus/nightshift/blob/main/internal/integrations/integrations.go) (Repository integrations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_commands["CLI commands"]
  node_config["Configuration<br/>[config.go]"]
  node_setup["Guided setup<br/>[presets.go]"]
end

subgraph group_planning["Planning and budgets"]
  node_scheduler["Schedule<br/>[scheduler.go]"]
  node_projects["Projects<br/>[projects.go]"]
  node_tasks["Task catalog<br/>[tasks.go]"]
  node_selector["Task selection<br/>[selector.go]"]
  node_budget["Budget allocation<br/>[budget.go]"]
end

subgraph group_execution["Task execution"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.go]"]
  node_agents["Agent adapters<br/>[agent.go]"]
  node_security["Security controls<br/>[security.go]"]
end

subgraph group_persistence["State and reporting"]
  node_database[("SQLite database<br/>[db.go]")]
  node_state["Run state<br/>[state.go]"]
  node_reporting["Run reports<br/>[run_report.go]"]
  node_analysis["Analysis and trends<br/>[analyzer.go]"]
  node_snapshots["Budget snapshots<br/>[collector.go]"]
end

subgraph group_integrations["External integrations"]
  node_providers["Usage providers<br/>[provider.go]"]
  node_integrations["Repository integrations<br/>[integrations.go]"]
end

node_user(("Operator"))
node_repos["Configured repositories"]
node_ai{{"AI CLIs"}}
node_github{{"GitHub"}}

node_user -->|"invokes"| node_commands
node_commands -->|"loads settings"| node_config
node_commands -->|"configures"| node_setup
node_commands -->|"previews schedule"| node_scheduler
node_commands -->|"selects projects"| node_projects
node_commands -->|"checks allowance"| node_budget
node_commands -->|"previews tasks"| node_selector
node_selector -->|"scores definitions"| node_tasks
node_budget -->|"reads usage"| node_providers
node_commands -->|"starts runs"| node_orchestrator
node_orchestrator -->|"executes phases"| node_agents
node_agents -->|"runs agent CLI"| node_ai
node_orchestrator -->|"applies controls"| node_security
node_orchestrator -->|"works in"| node_repos
node_orchestrator -->|"records progress"| node_state
node_state -->|"reads and writes"| node_database
node_commands -->|"presents results"| node_reporting
node_reporting -->|"persists run data"| node_database
node_commands -->|"requests analysis"| node_analysis
node_analysis -->|"reads run data"| node_database
node_commands -->|"captures usage"| node_snapshots
node_snapshots -->|"stores snapshots"| node_database
node_orchestrator -.->|"uses integrations"| node_integrations
node_integrations -.->|"creates PRs"| node_github
node_integrations -.->|"inspects repository"| node_repos

click node_commands "https://github.com/marcus/nightshift/tree/main/cmd/nightshift/commands"
click node_config "https://github.com/marcus/nightshift/blob/main/internal/config/config.go"
click node_setup "https://github.com/marcus/nightshift/blob/main/internal/setup/presets.go"
click node_scheduler "https://github.com/marcus/nightshift/blob/main/internal/scheduler/scheduler.go"
click node_projects "https://github.com/marcus/nightshift/blob/main/internal/projects/projects.go"
click node_tasks "https://github.com/marcus/nightshift/blob/main/internal/tasks/tasks.go"
click node_selector "https://github.com/marcus/nightshift/blob/main/internal/tasks/selector.go"
click node_budget "https://github.com/marcus/nightshift/blob/main/internal/budget/budget.go"
click node_providers "https://github.com/marcus/nightshift/blob/main/internal/providers/provider.go"
click node_orchestrator "https://github.com/marcus/nightshift/blob/main/internal/orchestrator/orchestrator.go"
click node_agents "https://github.com/marcus/nightshift/blob/main/internal/agents/agent.go"
click node_security "https://github.com/marcus/nightshift/blob/main/internal/security/security.go"
click node_database "https://github.com/marcus/nightshift/blob/main/internal/db/db.go"
click node_state "https://github.com/marcus/nightshift/blob/main/internal/state/state.go"
click node_reporting "https://github.com/marcus/nightshift/blob/main/internal/reporting/run_report.go"
click node_analysis "https://github.com/marcus/nightshift/blob/main/internal/analysis/analyzer.go"
click node_snapshots "https://github.com/marcus/nightshift/blob/main/internal/snapshots/collector.go"
click node_integrations "https://github.com/marcus/nightshift/blob/main/internal/integrations/integrations.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_commands,node_config,node_setup toneBlue
class node_scheduler,node_projects,node_tasks,node_selector,node_budget toneAmber
class node_orchestrator,node_agents,node_security toneMint
class node_database,node_state,node_reporting,node_analysis,node_snapshots toneRose
class node_providers,node_integrations,node_user,node_repos,node_ai,node_github toneIndigo
```

## Components

### CLI and setup

- [CLI commands](https://github.com/marcus/nightshift/tree/main/cmd/nightshift/commands): `cmd/nightshift/commands`
- [Configuration](https://github.com/marcus/nightshift/blob/main/internal/config/config.go): `internal/config/config.go`
- [Guided setup](https://github.com/marcus/nightshift/blob/main/internal/setup/presets.go): `internal/setup/presets.go`

### Planning and budgets

- [Schedule](https://github.com/marcus/nightshift/blob/main/internal/scheduler/scheduler.go): `internal/scheduler/scheduler.go`
- [Projects](https://github.com/marcus/nightshift/blob/main/internal/projects/projects.go): `internal/projects/projects.go`
- [Task catalog](https://github.com/marcus/nightshift/blob/main/internal/tasks/tasks.go): `internal/tasks/tasks.go`
- [Task selection](https://github.com/marcus/nightshift/blob/main/internal/tasks/selector.go): `internal/tasks/selector.go`
- [Budget allocation](https://github.com/marcus/nightshift/blob/main/internal/budget/budget.go): `internal/budget/budget.go`

### Task execution

- [Run orchestrator](https://github.com/marcus/nightshift/blob/main/internal/orchestrator/orchestrator.go): `internal/orchestrator/orchestrator.go`
- [Agent adapters](https://github.com/marcus/nightshift/blob/main/internal/agents/agent.go): `internal/agents/agent.go`
- [Security controls](https://github.com/marcus/nightshift/blob/main/internal/security/security.go): `internal/security/security.go`

### State and reporting

- [SQLite database](https://github.com/marcus/nightshift/blob/main/internal/db/db.go): `internal/db/db.go`
- [Run state](https://github.com/marcus/nightshift/blob/main/internal/state/state.go): `internal/state/state.go`
- [Run reports](https://github.com/marcus/nightshift/blob/main/internal/reporting/run_report.go): `internal/reporting/run_report.go`
- [Analysis and trends](https://github.com/marcus/nightshift/blob/main/internal/analysis/analyzer.go): `internal/analysis/analyzer.go`
- [Budget snapshots](https://github.com/marcus/nightshift/blob/main/internal/snapshots/collector.go): `internal/snapshots/collector.go`

### External integrations

- [Usage providers](https://github.com/marcus/nightshift/blob/main/internal/providers/provider.go): `internal/providers/provider.go`
- [Repository integrations](https://github.com/marcus/nightshift/blob/main/internal/integrations/integrations.go): `internal/integrations/integrations.go`

### Other components

- **Operator**
- **Configured repositories**
- **AI CLIs**
- **GitHub**

## Connections

- Operator → CLI commands: invokes
- CLI commands → Configuration: loads settings
- CLI commands → Guided setup: configures
- CLI commands → Schedule: previews schedule
- CLI commands → Projects: selects projects
- CLI commands → Budget allocation: checks allowance
- CLI commands → Task selection: previews tasks
- Task selection → Task catalog: scores definitions
- Budget allocation → Usage providers: reads usage
- CLI commands → Run orchestrator: starts runs
- Run orchestrator → Agent adapters: executes phases
- Agent adapters → AI CLIs: runs agent CLI
- Run orchestrator → Security controls: applies controls
- Run orchestrator → Configured repositories: works in
- Run orchestrator → Run state: records progress
- Run state → SQLite database: reads and writes
- CLI commands → Run reports: presents results
- Run reports → SQLite database: persists run data
- CLI commands → Analysis and trends: requests analysis
- Analysis and trends → SQLite database: reads run data
- CLI commands → Budget snapshots: captures usage
- Budget snapshots → SQLite database: stores snapshots
- Run orchestrator → Repository integrations: uses integrations
- Repository integrations → GitHub: creates PRs
- Repository integrations → Configured repositories: inspects repository