b1e55ed/
├── api/                    # FastAPI app and routes
│   ├── main.py             # App factory, router mounts
│   ├── auth.py             # Bearer token auth
│   ├── deps.py             # FastAPI dependencies
│   └── routes/             # Route modules by domain
├── engine/                 # Core engine
│   ├── brain/              # Brain orchestration
│   ├── core/               # DB, config, events, webhooks
│   ├── integrations/       # EAS, forge, oracle
│   ├── producers/          # Signal producers
│   └── strategies/         # Backtest strategies
├── dashboard/              # Starlette dashboard
├── docs/                   # Documentation
├── tests/                  # Test suite
│   ├── unit/               # Fast, isolated tests
│   └── integration/        # End-to-end tests
├── config/                 # Config files
│   ├── default.yaml        # Repo defaults
│   └── user.yaml           # Operator overlay (gitignored)
└── scripts/                # Utilities and validation

uv run pytest --ignore=tests/unit/test_eas_client.py -x -q

uv run pytest tests/unit/test_brain.py -v

# engine/producers/your_producer.py

from engine.core.db import EventStore
from engine.core.events import emit_event

class YourProducer:
    """Generates signals from [your source]."""

    name = "your_producer"
    domain = "technical"  # or: onchain, social, tradfi, curator

    def __init__(self, config: dict):
        self.config = config

    def run(self, db: EventStore) -> list[str]:
        """Run one cycle. Return list of emitted event IDs."""
        event_ids = []

        # Fetch data, compute signal
        direction = "bullish"  # or: bearish, neutral
        conviction = 7.0

        event_id = emit_event(
            db=db,
            event_type=f"signal.{self.domain}.your_signal.v1",
            source=f"producer.{self.name}",
            payload={
                "symbol": "BTC",
                "direction": direction,
                "conviction": conviction,
                "rationale": "...",
            },
        )
        event_ids.append(event_id)
        return event_ids

b1e55ed producers register \
  --name your_producer \
  --domain technical \
  --endpoint http://localhost:8001/poll \
  --schedule "*/15 * * * *"

# tests/unit/test_your_producer.py

def test_your_producer_emits_signal(tmp_db):
    producer = YourProducer(config={})
    event_ids = producer.run(tmp_db)
    assert len(event_ids) > 0

# engine/strategies/your_strategy.py

from engine.strategies.base import BaseStrategy

class YourStrategy(BaseStrategy):
    """Multi-factor strategy combining [signals]."""

    name = "your_strategy"

    def evaluate(self, signals: list[dict]) -> list[dict]:
        """Return list of trade intents."""
        intents = []
        # Group by symbol, check consensus, size via Kelly
        return intents

uv run pytest --ignore=tests/unit/test_eas_client.py -x -q   # tests
uv run ruff check .                                            # lint
uv run ruff format --check .                                   # format
bash scripts/validate_doc_deps.sh                              # doc deps