DESIGN.md

RMI Backend — 2026 Architecture Design

Why this exists

The current backend (/root/backend/) has grown organically:

• main.py is 10,305 lines
• 124 router files flat in app/routers/
• 14 RAG modules scattered at top of app/
• token_scanner.py is 4,109 lines
• x402_tools.py is 5,817 lines
• Cross-cutting concerns (redis, auth, errors) duplicated across modules
• Domain logic entangled with FastAPI
• No tests, no type safety, no clear boundaries

15 mechanical refactor tasks would patch symptoms. This design fixes the architecture.

Target Layout

/root/backend/
├── pyproject.toml              uv + ruff + mypy + pytest config (single source)
├── .pre-commit-config.yaml     ruff + mypy + size cap + gitleaks
├── Dockerfile
├── alembic/                    async migrations
│
├── app/
│   ├── main.py                 <100 lines: app factory + lifespan + middleware ONLY
│   ├── config.py               pydantic-settings, env loading
│   │
│   ├── core/                   cross-cutting, NO business logic
│   │   ├── logging.py          structlog JSON + correlation ID
│   │   ├── errors.py           AppError hierarchy + FastAPI handlers
│   │   ├── redis.py            async client + get_redis() Depends()
│   │   ├── db.py               async SQLAlchemy session
│   │   ├── auth.py             JWT decode + role guards
│   │   ├── lifespan.py         startup/shutdown
│   │   ├── middleware.py       CORS, rate limit, correlation ID
│   │   ├── websocket.py        WS connection manager
│   │   ├── tracing.py          OpenTelemetry + Langfuse v4 init
│   │   ├── http.py             async httpx client
│   │   └── pagination.py       cursor-based
│   │
│   ├── api/                    HTTP transport, thin routes
│   │   ├── deps.py             shared Depends (current_user, redis, etc)
│   │   ├── v1/
│   │   │   ├── public/         no auth  — scanner, wallet, token, pricing, health
│   │   │   ├── auth/           JWT      — portfolio, alerts, intel, profile
│   │   │   ├── admin/          admin    — users, system, ops
│   │   │   ├── x402/           paid     — tools, tokens, wallets, defi, security
│   │   │   └── mcp/            MCP      — tools.py
│   │   └── ws/                 WebSocket
│   │       └── alerts.py
│   │
│   ├── domain/                 pure business logic, NO FastAPI imports
│   │   ├── scanner/            core + honeypot + rugcheck + holders + contract + deployer + models + service
│   │   ├── wallet/             analyzer + labels + behavior + models + service
│   │   ├── token/              discovery + supply + models + service
│   │   ├── rag/                embeddings + chunking + search + ingest + firehose + feedback + agentic + evaluation + tracing + router + permanence + models + service
│   │   ├── x402/               facilitator + tokens + enforcement + settlement + models + service
│   │   ├── intel/              feeds + narratives + graph + models + service
│   │   ├── scam/               classifier + patterns + models + service
│   │   ├── databus/            client + chains(96) + models + service
│   │   └── bulletin/           board + models + service
│   │
│   ├── infra/                  external integrations
│   │   ├── ollama.py
│   │   ├── langfuse.py
│   │   ├── vector_store.py
│   │   ├── chains/             evm + solana + bitcoin + base + ...
│   │   ├── apis/               coingecko + etherscan + birdeye + goplus + ...
│   │   └── providers/          ollama + openrouter + huggingface + ...
│   │
│   └── workers/                background jobs (separate from API)
│       ├── firehose.py
│       ├── scanner_queue.py
│       ├── ingest_cron.py
│       └── cleanup.py
│
└── tests/
    ├── conftest.py
    ├── unit/domain/
    └── integration/api/v1/

Key Design Principles

1. STRICT LAYERING. api → domain → infra. Never reverse. Domain knows nothing about HTTP.
2. ONE SOURCE OF TRUTH for cross-cutting. redis/auth/errors/logging live in core/ exactly once. Routes import, never redefine.
3. HARD SIZE CAP. 500 lines per file. Enforced in pre-commit. No 4,109-line token_scanner.py ever again.
4. THIN ROUTES. Routes parse → call service → return. No business logic in HTTP layer.
5. DOMAIN = PURE PYTHON. domain/scanner/ can be unit tested without spinning up FastAPI. This is the test that proves the architecture.
6. WORKERS SEPARATED. Background jobs don't pollute the API. firehose, scanner_queue, ingest_cron live in workers/.
7. PYDANTIC V2 EVERYWHERE. Every domain has models.py. No dict types crossing boundaries.
8. ASYNC-ONLY. No sync I/O in handlers. Same shape for the whole codebase.
9. OBSERVABILITY BY DEFAULT. structlog JSON + correlation ID + OTel + Langfuse in core/tracing.py. Every endpoint instrumented without opt-in.
10. STRANGLER FIG MIGRATION. New skeleton co-exists with old code. Old main.py keeps importing the old routers. New routes added alongside. Per-domain cutover, not big-bang.

Migration Order

Order	Domain	Why
0	rag_engine shim	unblock prod crash, temp until app/rag/ lands
1	core/	foundation everyone depends on
2	infra/	external integrations domain depends on
3	alerts	smallest, well-bounded, has WS + JWT + redis — proves full pattern
4	wallet	high-value, used by frontend
5	token	high-value
6	scanner	biggest (4,109 lines), do last when pattern is mature
7	x402	payment system, critical, mature pattern by then
8	intel, scam, databus, bulletin	long tail
9	rag consolidation (was 14 files)	last because it's the most coupled

What Ships This Pass (Foundation)

1. Fix crash — rag_engine re-export shim, backend healthy
2. pyproject.toml — uv + ruff + mypy strict + pytest
3. .pre-commit-config.yaml — ruff + mypy + size cap (500) + gitleaks
4. app/core/ — 11 modules, each <200 lines
5. app/api/v1/__init__.py — router aggregator that still imports OLD routers (zero breakage)
6. app/main.py — rewritten to ~100 lines, calls lifespan + middleware from core/, mounts new aggregator
7. Verify: backend boots, all 757 routes respond, health 200, no import errors
8. Commit + deploy

What Does NOT Ship This Pass

• Migrating alerts/wallet/token/scanner to new domain/. That's Phase 2.
• The 15 mechanical refactors. Replaced with the layered architecture.
• Deleting old code. Strangler fig — old stays until domain is migrated.

Phase 2: Alerts Vertical Slice (proves the pattern)

After foundation lands, migrate alerts end-to-end as the reference:

app/domain/alerts/
├── models.py      # Alert, AlertRule, Notification — Pydantic v2
├── repository.py  # async SQLAlchemy queries
├── service.py     # business logic, pure Python
└── broadcaster.py # WebSocket broadcast helper

app/api/v1/auth/alerts.py  # thin route: parse → call service → return

This proves the pattern works: domain is pure Python, route is <100 lines, can be unit tested without HTTP.

When alerts is shipped and verified in prod, the same pattern is applied to wallet, token, scanner, etc.