# starq-technologies-pvt-ltd/starq-pm architecture

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

- Interactive diagram: https://gitdiagram.com/starq-technologies-pvt-ltd/starq-pm
- Repository: https://github.com/starq-technologies-pvt-ltd/starq-pm

## Overview

starq-pm is a governed project-lifecycle plugin for Hermes. Occupants submit actions through model-facing tools or the CLI; a shared runner checks governance, dispatches domain handlers, and commits accepted events to the hash-chained store. The domains cover charter and gates, requirements, planning, execution, independent verification, risk, monitoring, and closure; reports and flow metrics are additional capabilities. The excerpts show the runner, governance checks, storage, and several handlers. Some surface wiring and domain interactions are documented in the README but not shown in source excerpts.

Main entry points: [`domains/__init__.py`](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/__init__.py) (Domain registry), [`governance.py`](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/governance.py) (Governance), [`operations.py`](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/operations.py) (Action runner), [`domains/planning.py`](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/planning.py) (Planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_plugin["Plugin entry<br/>[__init__.py]"]
  node_tools["Model tools<br/>[tools.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_control["Governed runtime"]
  node_runner["Action runner<br/>[operations.py]"]
  node_governance["Governance<br/>[governance.py]"]
  node_defaults["Policy defaults<br/>[defaults.py]"]
  node_registry["Domain registry<br/>[__init__.py]"]
end

subgraph group_lifecycle["Project lifecycle"]
  node_initiation["Charter and gates<br/>[initiation.py]"]
  node_requirements["Requirements<br/>[requirements.py]"]
  node_planning["Planning<br/>[planning.py]"]
  node_execution["Execution<br/>[execution.py]"]
  node_closure["Closure<br/>[closure.py]"]
end

subgraph group_assurance["Quality and risk"]
  node_quality["Verification and quality<br/>[quality.py]"]
  node_risk["Risk and issues<br/>[risk.py]"]
end

subgraph group_insight["Records and insight"]
  node_store[("Event store<br/>[engine.py]")]
  node_monitoring["Change and reports<br/>[monitoring.py]"]
  node_measurement["Flow metrics<br/>[measurement.py]"]
end

node_occupant(("Occupant"))

node_occupant -->|"submits actions"| node_tools
node_occupant -->|"submits actions"| node_cli
node_plugin -->|"exposes tools"| node_tools
node_plugin -->|"exposes CLI"| node_cli
node_tools -->|"uses same actions"| node_runner
node_cli -->|"uses same actions"| node_runner
node_runner -->|"checks authority"| node_governance
node_runner -->|"dispatches action"| node_registry
node_registry -->|"registers handlers"| node_initiation
node_registry -->|"registers handlers"| node_requirements
node_registry -->|"registers handlers"| node_planning
node_registry -->|"registers handlers"| node_execution
node_registry -->|"registers handlers"| node_quality
node_registry -->|"registers handlers"| node_risk
node_registry -->|"registers handlers"| node_monitoring
node_registry -->|"registers handlers"| node_closure
node_runner -->|"appends events"| node_store
node_initiation -->|"uses guards"| node_governance
node_requirements -->|"uses guards"| node_governance
node_planning -->|"uses guards"| node_governance
node_execution -->|"uses guards"| node_governance
node_quality -->|"uses guards"| node_governance
node_risk -->|"uses guards"| node_governance
node_monitoring -->|"uses guards"| node_governance
node_closure -->|"reads events"| node_store
node_monitoring -->|"uses metrics"| node_measurement
node_planning -->|"uses metrics"| node_measurement
node_closure -->|"uses metrics"| node_measurement
node_governance -->|"loads defaults"| node_defaults

click node_plugin "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/__init__.py"
click node_tools "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/tools.py"
click node_cli "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/cli.py"
click node_runner "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/operations.py"
click node_governance "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/governance.py"
click node_store "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/engine.py"
click node_initiation "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/initiation.py"
click node_requirements "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/requirements.py"
click node_planning "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/planning.py"
click node_execution "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/execution.py"
click node_quality "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/quality.py"
click node_risk "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/risk.py"
click node_monitoring "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/monitoring.py"
click node_closure "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/closure.py"
click node_measurement "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/measurement.py"
click node_defaults "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/defaults.py"
click node_registry "https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/__init__.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_plugin,node_tools,node_cli toneBlue
class node_runner,node_governance,node_defaults,node_registry toneAmber
class node_initiation,node_requirements,node_planning,node_execution,node_closure toneMint
class node_quality,node_risk toneRose
class node_store,node_monitoring,node_measurement,node_occupant toneIndigo
```

## Components

### User interfaces

- [Plugin entry](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/__init__.py): `__init__.py`
- [Model tools](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/tools.py): `tools.py`
- [CLI](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/cli.py): `cli.py`

### Governed runtime

- [Action runner](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/operations.py): `operations.py`
- [Governance](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/governance.py): `governance.py`
- [Policy defaults](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/defaults.py): `defaults.py`
- [Domain registry](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/__init__.py): `domains/__init__.py`

### Project lifecycle

- [Charter and gates](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/initiation.py): `domains/initiation.py`
- [Requirements](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/requirements.py): `domains/requirements.py`
- [Planning](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/planning.py): `domains/planning.py`
- [Execution](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/execution.py): `domains/execution.py`
- [Closure](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/closure.py): `domains/closure.py`

### Quality and risk

- [Verification and quality](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/quality.py): `domains/quality.py`
- [Risk and issues](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/risk.py): `domains/risk.py`

### Records and insight

- [Event store](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/engine.py): `engine.py`
- [Change and reports](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/domains/monitoring.py): `domains/monitoring.py`
- [Flow metrics](https://github.com/starq-technologies-pvt-ltd/starq-pm/blob/main/measurement.py): `measurement.py`

### Other components

- **Occupant**

## Connections

- Occupant → Model tools: submits actions (evidence: `README.md`)
- Occupant → CLI: submits actions (evidence: `README.md`)
- Plugin entry → Model tools: exposes tools (evidence: `__init__.py`)
- Plugin entry → CLI: exposes CLI (evidence: `__init__.py`)
- Model tools → Action runner: uses same actions (evidence: `README.md`)
- CLI → Action runner: uses same actions (evidence: `README.md`)
- Action runner → Governance: checks authority (evidence: `operations.py`)
- Action runner → Domain registry: dispatches action (evidence: `operations.py`)
- Domain registry → Charter and gates: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Requirements: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Planning: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Execution: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Verification and quality: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Risk and issues: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Change and reports: registers handlers (evidence: `domains/__init__.py`)
- Domain registry → Closure: registers handlers (evidence: `domains/__init__.py`)
- Action runner → Event store: appends events (evidence: `operations.py`)
- Charter and gates → Governance: uses guards (evidence: `domains/initiation.py`)
- Requirements → Governance: uses guards (evidence: `domains/requirements.py`)
- Planning → Governance: uses guards (evidence: `domains/planning.py`)
- Execution → Governance: uses guards (evidence: `domains/execution.py`)
- Verification and quality → Governance: uses guards (evidence: `domains/quality.py`)
- Risk and issues → Governance: uses guards (evidence: `domains/risk.py`)
- Change and reports → Governance: uses guards (evidence: `domains/monitoring.py`)
- Closure → Event store: reads events (evidence: `domains/closure.py`)
- Change and reports → Flow metrics: uses metrics (evidence: `domains/monitoring.py`)
- Planning → Flow metrics: uses metrics (evidence: `domains/planning.py`)
- Closure → Flow metrics: uses metrics (evidence: `domains/closure.py`)
- Governance → Policy defaults: loads defaults (evidence: `governance.py`)
