Karvey Architecture

Karvey Architecture

Purpose

Generate the enterprise architecture technical design: components, boundaries, integrations, security controls per tier, observability, and a concrete file structure per layer.

Execution steps

Step 1 — Load context

Read in parallel:

• docs/spec/changes/{change-id}/spec.json (security_tier, layers, capability)
• docs/spec/changes/{change-id}/requirements.md
• docs/spec/changes/{change-id}/design-spec.md
• docs/spec/project.json (cloud.provider, iac_tool, git_platform, standards)
• rules/security-tiers.md
• rules/engineering-standards.md
• Engineering standards for the change's layers/targets: resolve project.json:standards (or docs/spec/standards/_index.md) and read the relevant standards/{layer}.md. These are a hard constraint on this design, not a suggestion. If no standard exists for a layer, announce it and treat every non-trivial pattern choice for that layer as a gray zone to ask (never silently pick one).
• Project steering: product.md, tech.md or equivalents if they exist

Verify approvals.design_graphic.approved = true. If not, stop.

Step 2 — Architecture discovery

For features that extend the existing system (brownfield):

Dispatch subagents to explore in parallel:

• Subagent A: grep -r of existing patterns related to the capability
• Subagent B: read existing endpoints/SPs of the affected area

Identify:

• Existing code patterns to follow (naming, function structure, error handling)
• Existing data access and its signatures (SPs, queries, ORM models, repositories, etc.)
• Existing API endpoints / operations and their contracts
• External integrations that already exist

For completely new features (greenfield):

• Define new patterns coherent with the existing stack

Step 3 — Classify architectural complexity

Step 4 — Generate architecture.md draft

Required structure:

# Architecture: {change-id}

## Summary
{1 paragraph: what it solves and how, at a high level}

## Diagrams (MANDATORY — at least one)

This architecture MUST include at least one mermaid diagram: **data flow** and/or **components**. Recommended to generate it with the cross-cutting `karvey-diagram` skill, which produces mermaid coherent with the rest of the spec.

```mermaid
{component or data flow diagram — ideally generated with /karvey-diagram}

Minimum required: 1 diagram. For "Complex integration" or "New capability" features, include both (components + data flow).

System boundary

This spec owns:

• {component/endpoint/SP 1}
• {component/endpoint/SP 2}

This spec does NOT touch:

• {existing component that is kept}
• {adjacent functionality out of scope}

Changes that require revalidating this design:

• {condition 1 that would make this design obsolete}

Components and responsibilities

DB layer

DB security controls:

• User context validation in every query/SP: YES/NO
• Typed parameters (no dynamic SQL/query): YES/NO
• Logging of critical operations: YES/NO

Backend layer

Backend security controls:

• Authentication required: Tier {N} → {mechanism: JWT, session, API key, etc.}
• Per-request user context validation: YES/NO
• Input sanitization at boundaries: YES/NO
• Error handling without exposing stack traces: YES/NO
• Sensitive variables via secrets manager: YES/NO

Frontend layer

Frontend security controls:

• Auth checks on routes: Frontend only as UX, enforcement in the backend
• Do not expose other tenants' data in the store
• Sanitization of dynamic outputs (no unsanitized v-html)

External integrations

Cloud infrastructure

Cloud provider(s): {from project.json cloud.provider. If mixed, explicitly specify which part of the system runs in which cloud — e.g.: "backend and DB on Azure; file storage on GCP Cloud Storage"}

Region(s) / zone: {e.g. East US 2 / southamerica-west1}

IaC tool: {from project.json iac_tool}. The IaC code will live in {where — e.g. infra/ of the corresponding repo, or a dedicated infra repo}.

Deployment trigger: push to dev → deploy DEV; merge to master → deploy PROD. Always triggered by the pipeline, NEVER manual.

The IaC detail (modules, concrete resources) and pipelines are generated by PHASE 6 (/karvey-infra). This section only declares which services from which cloud are used at the design level.

Main data flow

{Actor} → {Frontend} → {API Gateway / BFF} → {Backend} → {DB / Service}
                                                    ↓
                                         {External system}

Describe the flow step by step for the main use case:

1. {step 1: what the actor does}
2. {step 2: how the frontend responds}
3. {step N: what is persisted in the DB}

Trust boundaries

Explicitly mark WHERE untrusted input enters and WHERE it is validated. Any data crossing a boundary inward must be validated/sanitized at that crossing.

Rule: no data from the untrusted side is used without validation. Mark each trust boundary crossing in the data flow diagram (e.g. dotted line -. untrusted .->).

Security control points

File plan (concrete)

Files to CREATE

Files to MODIFY

DB files

Observability strategy

• Structured logging at: {log points}
• Metrics to track: {list}
• Recommended alerts: {list}
• Request traceability: {correlationId, userId/contextKey in every log}

Architectural decisions

Risks and mitigations

Edge cases (MANDATORY)

List the identified edge cases and how the design handles them. Cover at least: empty/null inputs, out-of-range values, concurrency/duplicates, external dependency failures (timeout, error, unavailability), inconsistent data, and size/quantity limits.

Test coverage plan (feeds /karvey-test)

Declare what is tested and at which level. Every requirement and every critical edge case must have at least one associated test at some level.

This table is the testing contract that /karvey-test consumes in the testing PHASE.

### Step 4B — Conformance gate against engineering standards

Before the review gate, classify the drafted design against the engineering standards loaded in Step 1 (`engineering-standards.md`). For each layer touched (DB / Backend / Frontend / Infra):

| Outcome | Action |
|---------|--------|
| ✅ **Conforms** to the golden path | Proceed. Cite the standard followed in "Architectural decisions". |
| ⚠️ **Gray zone, or must go outside the standard** | Do **NOT** decide alone. Emit a **Deviation Request** and ask the user **in design mode** (use `AskUserQuestion`). |
| ❌ **Violates a MUST / MUST NOT** with no justification | Block. Rework to conform, or escalate explicitly as a deviation. |

A **Deviation Request** presents: what the standard says · what this change needs instead · why (the driver) · options (recommended first, with the reason) · blast radius. On the user's approval, append the decision to `docs/spec/changes/{change-id}/deviations.md` (format in `engineering-standards.md`) and reference it in "Architectural decisions". Never resolve a deviation silently.

> Migration case (`Status: migrating`, e.g. frontend v2→v3): new work MUST use the `target` pattern. Designing against the `current`/`deprecated` pattern is a deviation — ask.

### Step 5 — Review gate

Verify before writing:
- [ ] Every requirement has at least one component that implements it
- [ ] The boundary is explicitly defined
- [ ] Each component has its Security Tier declared
- [ ] No components with vague responsibility ("helper", "utils" without a description)
- [ ] The file plan is concrete (real paths, not "create a file for X")
- [ ] The security controls cover the Tier declared in spec.json
- [ ] The Cloud Infrastructure section specifies which services from which cloud are used (and which part in which cloud if mixed)
- [ ] There is an observability strategy
- [ ] There is at least one mermaid diagram (data flow and/or components); for "Complex integration" / "New capability" both are present. Recommended to generate it with `/karvey-diagram`
- [ ] There is an Edge cases section covering at least: empty/null inputs, out of range, concurrency/duplicates, external system failures, and inconsistent data
- [ ] Trust boundaries are explicitly marked: where untrusted input enters and where each crossing is validated
- [ ] There is a Test coverage plan with a level (unit/integration/E2E) per item; every requirement and every critical edge case has at least one associated test
- [ ] The design conforms to the engineering standards of every layer touched, OR every departure has an approved entry in `deviations.md` (Step 4B); no MUST/MUST NOT is silently violated

If there are issues: fix and re-verify. Maximum 2 iterations.

### Step 6 — Write architecture.md

docs/spec/changes/{change-id}/architecture.md

Update `spec.json`:
- `phase: "architecture-generated"`
- `approvals.architecture.generated: true`

### Step 6B — Update knowledge graph

Sync the knowledge per `karvey/rules/knowledge-sync.md` (Obsidian if available; at minimum `/graphify docs/spec/ --update`) to reflect the created `architecture.md`.
If `docs/spec/graphify-out/` does not exist, invoke `/graphify docs/spec/` without `--update`.

### Step 7 — Present for approval

If flag `-y`: auto-approve.
If not: present a summary and ask for approval.

On approval: `approvals.architecture.approved: true`, `phase: "architecture-approved"`.

✅ Architecture approved

Next step: /karvey-infra {change-id}

## Advance to the next phase

When you finish this phase and have the corresponding approval, **actively ask the user**: "Shall we advance to the Infrastructure phase now?"
- If they confirm → run `/karvey-infra {change-id}`.
- If they prefer to review or adjust first → wait. Advancing is always with the user's OK (the method's gate).
- If you resume in another session, `/karvey {change-id}` shows which phase you are in and which one is next.

---
*Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see `karvey/LICENSE` and `karvey/TRADEMARK.md`.*