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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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