# Codebase Structure

**Analysis Date:** 2026-04-01

## Directory Layout

```
surfaces-bot/
├── adapter/
│   ├── __init__.py
│   └── matrix/              # matrix-nio adapter (merged to main)
│       ├── __init__.py
│       ├── bot.py           # Entry point, MatrixBot class, send_outgoing()
│       ├── converter.py     # nio Event → IncomingEvent
│       ├── reactions.py     # Emoji constants, skills text builder
│       ├── room_router.py   # room_id → chat_id resolution
│       ├── store.py         # Matrix-specific StateStore helpers (room meta, user meta)
│       └── handlers/
│           ├── __init__.py  # register_matrix_handlers()
│           ├── auth.py      # handle_invite (invite member event)
│           ├── chat.py      # Chat creation (creates real Matrix rooms)
│           ├── confirm.py   # Confirmation flow callbacks
│           └── settings.py  # Settings sub-commands and toggle_skill
├── core/
│   ├── auth.py              # AuthManager: start_flow, confirm, is_authenticated
│   ├── chat.py              # ChatManager: get_or_create, list_active, rename, archive
│   ├── handler.py           # EventDispatcher: register, dispatch, _routing_key
│   ├── protocol.py          # All shared dataclasses and type aliases
│   ├── settings.py          # SettingsManager: get (cached), apply (invalidates cache)
│   ├── store.py             # StateStore Protocol, InMemoryStore, SQLiteStore
│   └── handlers/
│       ├── __init__.py      # register_all() — binds all core handlers to dispatcher
│       ├── callback.py      # handle_confirm, handle_cancel, handle_toggle_skill
│       ├── chat.py          # handle_new_chat, handle_rename, handle_archive, handle_list_chats
│       ├── message.py       # handle_message — auth guard + platform.send_message
│       ├── settings.py      # handle_settings — displays settings menu
│       └── start.py         # handle_start — get_or_create_user + welcome message
├── sdk/
│   ├── __init__.py
│   ├── interface.py         # PlatformClient Protocol, WebhookReceiver Protocol, Pydantic models
│   └── mock.py              # MockPlatformClient — full in-memory implementation
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # (root conftest — sys.path fix for local sdk/ shadowing stdlib)
│   ├── adapter/
│   │   ├── __init__.py
│   │   ├── matrix/
│   │   │   ├── __init__.py
│   │   │   ├── test_converter.py
│   │   │   ├── test_dispatcher.py
│   │   │   ├── test_reactions.py
│   │   │   └── test_store.py
│   │   └── test_forum_db.py  # untracked — forum DB exploration
│   ├── core/
│   │   ├── test_auth.py
│   │   ├── test_chat.py
│   │   ├── test_dispatcher.py
│   │   ├── test_integration.py
│   │   ├── test_protocol.py
│   │   ├── test_settings.py
│   │   ├── test_store.py
│   │   └── test_voice_slot.py
│   └── platform/
│       └── test_mock.py
├── docs/                    # All human documentation
├── .planning/               # GSD planning artefacts
│   └── codebase/            # Codebase map documents (this directory)
├── .claude/
│   └── agents/              # Agent configuration files
├── .worktrees/
│   └── telegram/            # Telegram adapter on feat/telegram-adapter branch
│       └── ...              # Mirrors main layout; merged separately
├── conftest.py              # Root pytest conftest: sys.path hack for local sdk/
├── pyproject.toml           # Project metadata, dependencies, ruff + pytest config
├── uv.lock                  # Lockfile (uv)
├── lambda_matrix.db         # SQLite DB written by Matrix bot (gitignored)
└── .env.example             # Environment variable template
```

## Directory Purposes

**`core/`:**
- Purpose: Platform-neutral business logic. Never imports from `adapter/`.
- Key files: `protocol.py` (all shared types), `handler.py` (dispatcher), `store.py` (persistence interface)
- Add new domain logic here; keep it free of aiogram/matrix-nio imports

**`core/handlers/`:**
- Purpose: One async function per command/callback/message type. Each returns `list[OutgoingEvent]`.
- Registration: `register_all()` in `core/handlers/__init__.py` binds them to the dispatcher
- Adapters can override any key by calling `dispatcher.register(event_type, key, fn)` after `register_all()`

**`sdk/`:**
- Purpose: Contract (`interface.py`) and mock (`mock.py`) for the Lambda AI platform SDK
- Note: The directory is named `sdk/` in actual code (not `platform/` as CLAUDE.md describes); `handler.py` imports from `sdk.interface`
- When real SDK arrives: replace `sdk/mock.py` only; `sdk/interface.py` must not change unless the contract changes

**`adapter/matrix/`:**
- Purpose: Everything matrix-nio-specific. Translates between nio and core protocol.
- `bot.py` owns `MatrixBot`, `build_runtime()`, `send_outgoing()`, and `main()`
- `store.py` provides key-namespaced helpers on top of `StateStore` (not a separate store implementation)
- `room_router.py` maintains the `room_id → chat_id` mapping persisted in `StateStore`

**`adapter/telegram/`:**
- Purpose: aiogram 3.x adapter. Lives in `.worktrees/telegram/` on `feat/telegram-adapter` branch.
- Uses aiogram FSM states (`states.py`) and inline keyboards (`keyboards/`)
- Not yet merged to `main`

**`tests/`:**
- Purpose: pytest test suite mirroring the source tree
- `tests/core/` — unit tests for each core module
- `tests/adapter/matrix/` — Matrix adapter tests (converter, dispatcher, reactions, store)
- `tests/platform/` — MockPlatformClient tests

**`docs/`:**
- Purpose: Human-readable design documents; not consumed by code
- Key docs: `docs/surface-protocol.md` (unification rationale), `docs/api-contract.md` (SDK contract), `docs/telegram-prototype.md`, `docs/matrix-prototype.md`

## Key File Locations

**Entry Points:**
- `adapter/matrix/bot.py` — Matrix bot `main()`, run via `python -m adapter.matrix.bot`
- `.worktrees/telegram/adapter/telegram/bot.py` — Telegram bot entry (feature branch)

**Shared Protocol:**
- `core/protocol.py` — single source of truth for all inter-layer data types

**SDK Contract:**
- `sdk/interface.py` — `PlatformClient` Protocol; defines the API surface for the real SDK
- `sdk/mock.py` — `MockPlatformClient`; current runtime implementation

**Dispatcher Registration:**
- `core/handlers/__init__.py` — `register_all()` for platform-agnostic handlers
- `adapter/matrix/handlers/__init__.py` — `register_matrix_handlers()` for Matrix overrides

**Persistence:**
- `core/store.py` — `StateStore` Protocol, `InMemoryStore`, `SQLiteStore`
- `adapter/matrix/store.py` — Matrix-specific store helper functions (not a store implementation)

**Configuration:**
- `pyproject.toml` — dependencies, pytest config (`asyncio_mode = "auto"`, `pythonpath = ["."]`), ruff config
- `conftest.py` — `sys.path` insert so local `sdk/` shadows stdlib `platform` module

## Naming Conventions

**Files:**
- Modules: `snake_case.py`
- Entry points: `bot.py` per adapter
- Converter: `converter.py` per adapter
- Handlers directory: `handlers/` per layer

**Classes:**
- Managers: `{Domain}Manager` (e.g. `ChatManager`, `AuthManager`, `SettingsManager`)
- Bot runtime: `{Platform}Bot` (e.g. `MatrixBot`)
- Protocol types: PascalCase dataclasses (e.g. `IncomingMessage`, `OutgoingUI`)
- SDK types: PascalCase Pydantic models (e.g. `MessageResponse`, `UserSettings`)

**Handler functions:**
- `handle_{command}` for command handlers (e.g. `handle_start`, `handle_new_chat`)
- `make_handle_{command}` for factory functions that close over adapter state (e.g. `make_handle_new_chat(client, store)`)

**State keys:**
- `"{namespace}:{discriminator}"` — always use the prefix constants defined in `adapter/matrix/store.py`

## Where to Add New Code

**New core command handler:**
1. Add `async def handle_{cmd}(event, chat_mgr, auth_mgr, settings_mgr, platform) -> list` in `core/handlers/{category}.py`
2. Register it in `core/handlers/__init__.py:register_all()` with `dispatcher.register(IncomingCommand, "{cmd}", handle_{cmd})`
3. Write tests in `tests/core/test_dispatcher.py` or a dedicated `tests/core/test_{category}.py`

**New Matrix-specific handler (needs nio client or matrix store):**
1. Add handler in `adapter/matrix/handlers/{category}.py`
2. Register in `adapter/matrix/handlers/__init__.py:register_matrix_handlers()` — this overrides the core handler for that key

**New protocol type:**
- Add dataclass to `core/protocol.py`; update `IncomingEvent` or `OutgoingEvent` union aliases if it crosses layer boundaries
- Update `EventDispatcher._routing_key()` if it requires a new dispatch strategy

**New StateStore key namespace:**
- Add prefix constant and helper functions in `adapter/matrix/store.py` (for Matrix-specific state) or directly in the relevant manager (for core state)

**New test:**
- Unit tests for core logic: `tests/core/test_{module}.py`
- Adapter tests: `tests/adapter/matrix/test_{module}.py`
- Use `InMemoryStore` as the store; use `MockPlatformClient` as the platform client

## Special Directories

**`.worktrees/telegram/`:**
- Purpose: Git worktree for `feat/telegram-adapter` branch; full copy of the repo root
- Generated: Yes (via `git worktree add`)
- Committed: No (worktrees are local)

**`.planning/`:**
- Purpose: GSD planning artefacts — phase plans and codebase maps
- Generated: Yes (by `/gsd:` commands)
- Committed: Yes (tracked with the repo)

**`.claude/agents/`:**
- Purpose: Agent role configuration files for the multi-agent workflow
- Committed: Yes

**`src/`:**
- Purpose: Contains only `surfaces_bot.egg-info/` (setuptools build artefact); no source code
- Generated: Yes
- Committed: No

---

*Structure analysis: 2026-04-01*