Skip to content

docs: ARCHITECTURE.md — document post-consolidation crate boundaries #298

Description

@ajianaz

What

Create ARCHITECTURE.md documenting the post-cleanup 6-crate structure and where each feature actually lives.

Why

BMAD COO finding: There is no architecture document. Contributors must guess where code lives. After the v0.3.0 crate consolidation (9→6), documentation is critical to prevent future ghost-crate confusion.

Content Outline

  1. Overview — What TrapFall is, design philosophy (Rust, MCP-first, Sentry compat)
  2. Crate Map (post-consolidation):
    trapfall-proto    → Sentry protocol types (wire format)
    trapfall-db       → Data layer (SQLite + Postgres dual backend, migrations)
    trapfall-core     → Store abstraction, fingerprinting (Blake3)
    trapfall-ingest   → Envelope parser (Sentry SDK format)
    trapfall-mcp      → MCP server (12 tools)
    trapfalld         → Binary: HTTP server, auth, WebSocket, alert engine, SPA serving
    
  3. Feature Location Map:
    • Alerting → trapfalld/src/alert.rs (NOT a separate crate)
    • Dashboard → SvelteKit web/ served via trapfalld/src/spa.rs
    • Search → inline in trapfalld (delegates to trapfall-db)
    • Auth → trapfalld/src/auth.rs
    • Config → trapfalld/src/config.rs
  4. Data Flow: Sentry SDK → ingest endpoint → envelope parse → fingerprint → store → alert engine → webhook → dashboard WebSocket
  5. Testing Strategy: Where tests live, how to run them, testcontainers for Postgres
  6. Adding a Feature: Checklist (migration, proto types, db queries, handler, MCP tool, dashboard page, docs)

Testing

  • Review by reading as a new contributor — can they understand the architecture?
  • Cross-reference with actual code to verify accuracy

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpriority:mediumP2 - Fix in next batch

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions