# wfukatsu/nexus-architect architecture

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

- Interactive diagram: https://gitdiagram.com/wfukatsu/nexus-architect
- Repository: https://github.com/wfukatsu/nexus-architect

## Overview

#### Purpose and Entry Points
Nexus Architect is a prompt/skill-based architecture toolkit, not a deployed application. It runs in Claude Code as three plugins (`product`, `architect`, `scalardb`) or in Codex through compatibility instructions. Primary entry points are plugin metadata in `.claude-plugin/marketplace.json`, Codex translation rules in `AGENTS.md`, and skill definitions under `skills/**/SKILL.md`.

#### Runtime and Execution Model
Claude Code resolves slash commands to installed plugin skills; Codex reads the same Markdown skills and maps Claude-oriented paths/tools to local shell and editing behavior. Skills orchestrate an agent-driven workflow, writing project-local generated artifacts rather than executing a central service. Key compatibility and dependency definitions:
- `AGENTS.md`
- `skills/common/skill-dependencies.yaml`
- `skills/product/common/skill-dependencies.yaml`

Python 3.9+ supports hooks, migration extractors, and terminal dashboards; Node.js 18+ is optional for Mermaid rendering.

#### Product-to-Architecture Pipeline
The product plugin turns an early product idea into validated requirements and hands off to architecture design. Its main stages are vision/scope and assumption validation, UX/domain/API/data derivation, then SLA/NFR synthesis. The dependency boundary is `/architect:define-requirements`, which consumes product outputs as implementation-design inputs.
- `skills/product/start/SKILL.md`
- `skills/product/design-architecture/SKILL.md`
- `skills/define-requirements/SKILL.md`

#### Architect Analysis and Design Pipeline
The architect plugin supports legacy assessment and greenfield system design. Its core flow is: investigate/analyze existing or required system behavior; evaluate maturity and DDD fitness; redesign domains; design microservices, data layer/ScalarDB, and APIs; run multi-perspective reviews; consolidate reports. The formal greenfield sequencing is documented in:
- `workflow/greenfield/00_workflow_overview.md`
- `workflow/greenfield/01_requirements_analysis.md`
- `skills/pipeline/SKILL.md`

Reports, generated code, and workflow state are intentionally separated into target-project `reports/`, `generated/`, and `work/` directories.

#### ScalarDB Design and Knowledge Boundary
ScalarDB-specific skills provide schema, transaction, configuration, CRUD/JDBC, scaffolding, migration, and code-review guidance. Decisions are constrained by edition/version-aware official knowledge rather than generic advice. The knowledge bundle is a git submodule at `knowledge/okf-scalardb-scalardl`, with update lifecycle managed by:
- `skills/design-scalardb/SKILL.md`
- `skills/model/SKILL.md`
- `rules/okf-knowledge-bundle.md`

This boundary covers ScalarDB, ScalarDB Saga, and ScalarDL APIs, transaction patterns, and version-sensitive configuration.

#### Generation, Delivery, and External Integrations
Post-design code generation is a manual extension tier: implementation specs feed test specs, Spring Boot + ScalarDB code, infrastructure code, and documentation. Generated scaffolds stay disposable under `generated/`; backlog delivery instead edits the target repository’s real source tree and uses GitHub or GitLab issues/PRs/MRs as the merge-control boundary.
- `skills/design-implementation/SKILL.md`
- `skills/generate-scalardb-code/SKILL.md`
- `skills/deliver-backlog/SKILL.md`

Optional infrastructure/services include Kubernetes, Terraform, Helm, Docker Compose, GitHub/GitLab, Serena MCP for AST analysis, Context7 for current documentation, and Oracle/MySQL/PostgreSQL connections for migration analysis.

#### Observability and Workflow State
Terminal dashboards derive status, dependencies, stale phases, and token-cost reporting from workflow artifacts. Hooks validate generated front matter and Mermaid, while token usage can be recorded during agent runs.
- `tools/nexus-status.sh`
- `tools/lib/pipeline_status_data.py`
- `hooks/record_token_usage.py`

Main entry points: [`skills/pipeline/SKILL.md`](https://github.com/wfukatsu/nexus-architect/blob/main/skills/pipeline/SKILL.md) (Architect pipeline), [`skills/design-scalardb/SKILL.md`](https://github.com/wfukatsu/nexus-architect/blob/main/skills/design-scalardb/SKILL.md) (ScalarDB design), [`workflow/greenfield/01_requirements_analysis.md`](https://github.com/wfukatsu/nexus-architect/blob/main/workflow/greenfield/01_requirements_analysis.md) (Requirements analysis), [`skills/product/design-architecture/SKILL.md`](https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/design-architecture/SKILL.md) (Product architecture design)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Agent Runtime"]
  node_claude{{"Claude Code plugins<br/>agent runtime<br/>[marketplace.json]"}}
  node_codex{{"Codex compatibility<br/>agent runtime<br/>[AGENTS.md]"}}
  node_skills["Markdown skills<br/>skill catalog"]
  node_dependencies["Skill dependencies<br/>dependency rules"]
  node_product_dependencies["Product dependencies<br/>dependency rules"]
end

subgraph group_design["Product &amp; Architecture"]
  node_product_start["Product discovery<br/>product skill<br/>[SKILL.md]"]
  node_product_architecture["Product architecture design<br/>product skill<br/>[SKILL.md]"]
  node_requirements["Requirements boundary<br/>architect skill<br/>[SKILL.md]"]
  node_greenfield["Greenfield workflow"]
  node_requirements_analysis["Requirements analysis<br/>workflow stage"]
  node_architect_pipeline["Architect pipeline<br/>orchestration skill<br/>[SKILL.md]"]
end

subgraph group_scalardb["ScalarDB Boundary"]
  node_scalardb_design["ScalarDB design<br/>scalardb skill<br/>[SKILL.md]"]
  node_scalardb_model["ScalarDB modeling<br/>scalardb skill<br/>[SKILL.md]"]
  node_knowledge[("Official knowledge bundle<br/>git submodule")]
  node_knowledge_rules["Knowledge bundle rules<br/>policy"]
end

subgraph group_delivery["Generation &amp; Delivery"]
  node_implementation["Implementation specs<br/>design skill<br/>[SKILL.md]"]
  node_scaffold["ScalarDB code scaffolds<br/>generation skill<br/>[SKILL.md]"]
  node_backlog["Backlog delivery<br/>delivery skill<br/>[SKILL.md]"]
end

subgraph group_state["Workflow State &amp; Quality"]
  node_artifacts[("Target-project artifacts<br/>generated outputs")]
  node_dashboard["Terminal dashboard<br/>status tool<br/>[nexus-status.sh]"]
  node_status_data["Workflow status data<br/>python module"]
  node_token_hook["Token usage hook<br/>python hook"]
end

node_claude -->|"resolves commands to"| node_skills
node_codex -->|"reads and adapts"| node_skills
node_skills -.->|"uses"| node_dependencies
node_skills -.->|"uses"| node_product_dependencies
node_product_start -->|"validated product inputs"| node_product_architecture
node_product_architecture -->|"hands off requirements"| node_requirements
node_requirements -->|"drives"| node_requirements_analysis
node_greenfield -->|"defines sequence"| node_requirements_analysis
node_requirements_analysis -->|"feeds design"| node_architect_pipeline
node_architect_pipeline -->|"designs data layer"| node_scalardb_design
node_scalardb_design -->|"refines model"| node_scalardb_model
node_scalardb_design -->|"constrained by"| node_knowledge
node_knowledge_rules -->|"governs updates and use"| node_knowledge
node_architect_pipeline -->|"produces design inputs"| node_implementation
node_implementation -->|"feeds generation"| node_scaffold
node_scaffold -->|"writes generated outputs"| node_artifacts
node_backlog -.->|"reads reports and state"| node_artifacts
node_architect_pipeline -->|"writes reports and work state"| node_artifacts
node_artifacts -->|"supplies workflow artifacts"| node_dashboard
node_dashboard -->|"uses"| node_status_data
node_token_hook -->|"records usage in workflow state"| node_artifacts

click node_claude "https://github.com/wfukatsu/nexus-architect/blob/main/.claude-plugin/marketplace.json"
click node_codex "https://github.com/wfukatsu/nexus-architect/blob/main/AGENTS.md"
click node_dependencies "https://github.com/wfukatsu/nexus-architect/blob/main/skills/common/skill-dependencies.yaml"
click node_product_dependencies "https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/common/skill-dependencies.yaml"
click node_product_start "https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/start/SKILL.md"
click node_product_architecture "https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/design-architecture/SKILL.md"
click node_requirements "https://github.com/wfukatsu/nexus-architect/blob/main/skills/define-requirements/SKILL.md"
click node_greenfield "https://github.com/wfukatsu/nexus-architect/blob/main/workflow/greenfield/00_workflow_overview.md"
click node_requirements_analysis "https://github.com/wfukatsu/nexus-architect/blob/main/workflow/greenfield/01_requirements_analysis.md"
click node_architect_pipeline "https://github.com/wfukatsu/nexus-architect/blob/main/skills/pipeline/SKILL.md"
click node_scalardb_design "https://github.com/wfukatsu/nexus-architect/blob/main/skills/design-scalardb/SKILL.md"
click node_scalardb_model "https://github.com/wfukatsu/nexus-architect/blob/main/skills/model/SKILL.md"
click node_knowledge "https://github.com/wfukatsu/nexus-architect/tree/main/knowledge/okf-scalardb-scalardl"
click node_knowledge_rules "https://github.com/wfukatsu/nexus-architect/blob/main/rules/okf-knowledge-bundle.md"
click node_implementation "https://github.com/wfukatsu/nexus-architect/blob/main/skills/design-implementation/SKILL.md"
click node_scaffold "https://github.com/wfukatsu/nexus-architect/blob/main/skills/generate-scalardb-code/SKILL.md"
click node_backlog "https://github.com/wfukatsu/nexus-architect/blob/main/skills/deliver-backlog/SKILL.md"
click node_dashboard "https://github.com/wfukatsu/nexus-architect/blob/main/tools/nexus-status.sh"
click node_status_data "https://github.com/wfukatsu/nexus-architect/blob/main/tools/lib/pipeline_status_data.py"
click node_token_hook "https://github.com/wfukatsu/nexus-architect/blob/main/hooks/record_token_usage.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_claude,node_codex,node_skills,node_dependencies,node_product_dependencies toneBlue
class node_product_start,node_product_architecture,node_requirements,node_greenfield,node_requirements_analysis,node_architect_pipeline toneAmber
class node_scalardb_design,node_scalardb_model,node_knowledge,node_knowledge_rules toneMint
class node_implementation,node_scaffold,node_backlog toneRose
class node_artifacts,node_dashboard,node_status_data,node_token_hook toneIndigo
```

## Components

### Agent Runtime

- [Claude Code plugins](https://github.com/wfukatsu/nexus-architect/blob/main/.claude-plugin/marketplace.json): agent runtime · Runs product, architect, and scalardb plugin skills. · `.claude-plugin/marketplace.json`
- [Codex compatibility](https://github.com/wfukatsu/nexus-architect/blob/main/AGENTS.md): agent runtime · Maps shared skills to local shell and editing behavior. · `AGENTS.md`
- **Markdown skills**: skill catalog · Shared prompt-driven commands and workflow instructions.
- [Skill dependencies](https://github.com/wfukatsu/nexus-architect/blob/main/skills/common/skill-dependencies.yaml): dependency rules · `skills/common/skill-dependencies.yaml`
- [Product dependencies](https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/common/skill-dependencies.yaml): dependency rules · `skills/product/common/skill-dependencies.yaml`

### Product & Architecture

- [Product discovery](https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/start/SKILL.md): product skill · Derives vision, scope, and validated assumptions. · `skills/product/start/SKILL.md`
- [Product architecture design](https://github.com/wfukatsu/nexus-architect/blob/main/skills/product/design-architecture/SKILL.md): product skill · Derives UX, domains, APIs, data, and NFRs. · `skills/product/design-architecture/SKILL.md`
- [Requirements boundary](https://github.com/wfukatsu/nexus-architect/blob/main/skills/define-requirements/SKILL.md): architect skill · Consumes product outputs as implementation-design inputs. · `skills/define-requirements/SKILL.md`
- [Greenfield workflow](https://github.com/wfukatsu/nexus-architect/blob/main/workflow/greenfield/00_workflow_overview.md): workflow · Sequences requirements analysis through system design. · `workflow/greenfield/00_workflow_overview.md`
- [Requirements analysis](https://github.com/wfukatsu/nexus-architect/blob/main/workflow/greenfield/01_requirements_analysis.md): workflow stage · `workflow/greenfield/01_requirements_analysis.md`
- [Architect pipeline](https://github.com/wfukatsu/nexus-architect/blob/main/skills/pipeline/SKILL.md): orchestration skill · Analyzes, redesigns, reviews, and consolidates architecture work. · `skills/pipeline/SKILL.md`

### ScalarDB Boundary

- [ScalarDB design](https://github.com/wfukatsu/nexus-architect/blob/main/skills/design-scalardb/SKILL.md): scalardb skill · Designs schema, transactions, and configuration. · `skills/design-scalardb/SKILL.md`
- [ScalarDB modeling](https://github.com/wfukatsu/nexus-architect/blob/main/skills/model/SKILL.md): scalardb skill · `skills/model/SKILL.md`
- [Official knowledge bundle](https://github.com/wfukatsu/nexus-architect/tree/main/knowledge/okf-scalardb-scalardl): git submodule · Edition- and version-aware ScalarDB, Saga, and ScalarDL guidance. · `knowledge/okf-scalardb-scalardl`
- [Knowledge bundle rules](https://github.com/wfukatsu/nexus-architect/blob/main/rules/okf-knowledge-bundle.md): policy · `rules/okf-knowledge-bundle.md`

### Generation & Delivery

- [Implementation specs](https://github.com/wfukatsu/nexus-architect/blob/main/skills/design-implementation/SKILL.md): design skill · Feeds test, application, infrastructure, and documentation generation. · `skills/design-implementation/SKILL.md`
- [ScalarDB code scaffolds](https://github.com/wfukatsu/nexus-architect/blob/main/skills/generate-scalardb-code/SKILL.md): generation skill · Creates disposable Spring Boot and ScalarDB outputs. · `skills/generate-scalardb-code/SKILL.md`
- [Backlog delivery](https://github.com/wfukatsu/nexus-architect/blob/main/skills/deliver-backlog/SKILL.md): delivery skill · Edits the target repository and uses PR/MR workflow. · `skills/deliver-backlog/SKILL.md`

### Workflow State & Quality

- **Target-project artifacts**: generated outputs · Separates reports, generated code, and workflow state.
- [Terminal dashboard](https://github.com/wfukatsu/nexus-architect/blob/main/tools/nexus-status.sh): status tool · Computes status, dependencies, stale phases, and token costs. · `tools/nexus-status.sh`
- [Workflow status data](https://github.com/wfukatsu/nexus-architect/blob/main/tools/lib/pipeline_status_data.py): python module · `tools/lib/pipeline_status_data.py`
- [Token usage hook](https://github.com/wfukatsu/nexus-architect/blob/main/hooks/record_token_usage.py): python hook · Records agent token usage during runs. · `hooks/record_token_usage.py`

## Connections

- Claude Code plugins → Markdown skills: resolves commands to
- Codex compatibility → Markdown skills: reads and adapts
- Markdown skills → Skill dependencies: uses
- Markdown skills → Product dependencies: uses
- Product discovery → Product architecture design: validated product inputs
- Product architecture design → Requirements boundary: hands off requirements
- Requirements boundary → Requirements analysis: drives
- Greenfield workflow → Requirements analysis: defines sequence
- Requirements analysis → Architect pipeline: feeds design
- Architect pipeline → ScalarDB design: designs data layer
- ScalarDB design → ScalarDB modeling: refines model
- ScalarDB design → Official knowledge bundle: constrained by
- Knowledge bundle rules → Official knowledge bundle: governs updates and use
- Architect pipeline → Implementation specs: produces design inputs
- Implementation specs → ScalarDB code scaffolds: feeds generation
- ScalarDB code scaffolds → Target-project artifacts: writes generated outputs
- Backlog delivery → Target-project artifacts: reads reports and state
- Architect pipeline → Target-project artifacts: writes reports and work state
- Target-project artifacts → Terminal dashboard: supplies workflow artifacts
- Terminal dashboard → Workflow status data: uses
- Token usage hook → Target-project artifacts: records usage in workflow state