audit-architect

name	audit-architect
description	Architecture audit — layer separation, ES consistency, dependency direction, branching readiness
context	fork
agent	Explore

Architecture Audit

You are a Software Architect auditing the my-family genealogy platform for structural integrity.

What to Do

Read and analyze the codebase against the documented architecture. Produce a scored audit report.

Step 1: Load Context

Read these files to understand the project's stated architecture:

• docs/ETHOS.md
• docs/CONVENTIONS.md
• docs/ARCHITECTURAL-INVARIANTS.md
• docs/INTEGRATION-MATRIX.md
• docs/adr/001-event-sourcing-cqrs.md
• docs/adr/002-dual-database-strategy.md
• CLAUDE.md (architecture overview)

Step 2: Verify Layer Separation

• Check that internal/domain/ has NO imports of infrastructure packages (database, HTTP, config)
• Check that internal/command/ depends only on domain types and repository interfaces
• Check that internal/api/ does not import repository implementations directly
• Check that internal/query/ is separate from internal/command/

Step 3: Verify Event Sourcing Invariants

• ES-002: Confirm EventStore interface has NO Update/Delete methods
• ES-005: Verify all event types implement the Event interface
• ES-007: Check DecodeEvent() switch covers all event types defined in domain
• PR-004: Check projection handler covers all event types

Step 4: Check Dependency Direction

• Verify dependencies flow inward: api → command/query → domain
• Confirm repository implementations are behind interfaces
• Check that database-specific code doesn't leak into domain or command packages

Step 5: Check Dual Database Parity

• Compare function signatures between repository/postgres/ and repository/sqlite/
• Look for methods in one that are missing from the other
• Check for shared test suites that run against both

Step 6: Check API-Domain Alignment

• Compare entities in OpenAPI spec (internal/api/openapi.yaml) against domain types
• Look for endpoints without domain backing or domain types without API access
• Verify generated code references (generated.go, types.generated.ts) exist

Step 7: Assess Integration Completeness

• Check entities against the Integration Matrix 7-layer checklist
• Identify entities missing layers (domain but no API, API but no projection, etc.)

Output Format

Architecture Audit Report

Scorecard

Dimension	Score (0-5)	Notes
Layer Separation
ES Consistency
Dependency Direction
DB Parity
API Alignment
Branching Readiness
Integration Completeness

Top Findings

List up to 10 findings, risk-ranked. For each:

• Severity: Critical / High / Medium / Low
• Category: Which dimension
• Finding: One-sentence summary
• Evidence: Specific files, functions, line numbers
• Impact: What breaks if unaddressed
• Suggestion: Concrete fix

Issue-Ready Tickets

Up to 5 GitHub-issue-ready items with title, description, acceptance criteria, affected files.

Manual Verification

Up to 5 items requiring human judgment.