# Sonar Architecture Model

This document defines the intended module boundaries that Sonar architecture
analysis should eventually enforce for Open Orchestra. Until Sonar-specific
directives are configured, this is the portable source of truth for architecture
review, code review, and workflow gate evidence.

## Domains

### CLI and Command Surface

Files:

- `bin/`
- `src/*-commands.ts`
- `src/commands.ts`

Responsibilities:

- parse command input;
- call domain services;
- format CLI output;
- avoid business logic beyond validation and dispatch.

Expected dependencies:

- may depend on domain services, workflow services, config loaders, and typed
  output helpers;
- must not own persistence rules, workflow state transitions, provider routing,
  or web UI behavior.

### Workflow and Delivery Domain

Files:

- `src/workflow*.ts`
- `src/task*.ts`
- `src/release*.ts`
- `src/review*.ts`
- `src/evidence*.ts`
- `src/qa*.ts`

Responsibilities:

- task lifecycle;
- workflow phases and gates;
- handoffs, reviews, evidence, acceptance coverage, release readiness.

Expected dependencies:

- may depend on persistence helpers, domain types, policy checks, and prompt
  registry services;
- should expose narrow service APIs for command and web entry points.

### Runtime, Model, Budget, and Telemetry

Files:

- `src/model*.ts`
- `src/runtime*.ts`
- `src/budget*.ts`
- `src/telemetry*.ts`

Responsibilities:

- provider routing;
- model provenance;
- cost, token, runtime, and budget controls;
- telemetry consent, export, and submission audit.

Expected dependencies:

- may depend on workflow identifiers and policy/config types;
- must not depend on UI code or generated site assets.

### Profiles, Roles, Skills, and Guidance

Files:

- `src/profiles/`
- `src/roles/`
- `src/skills*.ts`
- `src/generators/`
- `src/prompt*.ts`
- `skills/`
- `rules/`

Responsibilities:

- role metadata;
- runtime capability selection;
- skill rendering;
- generated guidance and prompt registry validation.

Expected dependencies:

- may depend on shared domain types and generation utilities;
- must keep role/capability data centralized instead of hardcoding lists across
  commands or UI surfaces.

### Web API and Web Console

Files:

- `src/web-api*.ts`
- `src/web-console-client.js`
- `web-console/src/`

Responsibilities:

- expose local read/write APIs;
- render task, workflow, evidence, recovery, provider, and settings views;
- keep user-facing flows responsive, accessible, and evidence-oriented.

Expected dependencies:

- web API may depend on domain services;
- React/client code should not import Node-only modules or mutate workflow files
  directly.

### Site and Documentation Publishing

Files:

- `site/`
- `scripts/generate-site-content.js`
- `docs/site-manifest.json`
- public documentation under `docs/`

Responsibilities:

- generate and publish public documentation content;
- render docs-driven site pages;
- keep public docs separate from internal workflow evidence.

Expected dependencies:

- may read approved docs manifests and public content;
- must not depend on local workflow state, secrets, or private evidence.

### Extensions

Files:

- `extensions/`

Responsibilities:

- editor integration;
- command invocation adapters;
- local service bridge behavior.

Expected dependencies:

- may call public CLI/API contracts;
- should not duplicate workflow business rules already owned by `src/`.

## Boundary Rules

- Commands stay logic-light and delegate to services.
- Domain services do not import from web console, site, or extension code.
- Generated assets and docs do not become runtime sources of truth.
- Capability, role, provider, command, and workflow phase lists use centralized
  domain helpers instead of repeated hardcoded arrays.
- Security-sensitive code paths keep auth, secrets, file paths, shell execution,
  network calls, and provider credentials behind explicit services and tests.
- Architecture changes that cross these boundaries need an Orchestra decision or
  ADR-style note before implementation.

## Sonar Directive Adoption

When Sonar directive files are introduced, they should encode the domains above
as enforceable layers or dependency rules. The implementation task must include:

- the directive format supported by the connected Sonar edition;
- a failing/passing validation example;
- a Sonar run showing directives consumed by the architecture sensor;
- a review that maps any initial violations to GitHub issues or accepted risks.