Lucas WintherandClaude Opus 5
895eabcb69
Empty repository: no commits, no stack. Establishes AGENTS.md as the single source of truth, thin CLAUDE.md/GEMINI.md pointers, permission config, and the docs/ progressive-disclosure tree. Commands section is deliberately unfilled — no stack exists to verify commands against. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2.9 KiB
Architecture
How recoll-modern is built today. Update in the same commit as any structural change.
Overview
Nothing is built yet. This file currently records intent and the open questions that the first spec must close. Do not read anything below "Intended shape" as describing existing code.
The goal: a self-hosted service that wraps Recoll's indexing and full-text search behind (a) a modern
web UI and (b) an MCP server, running in Docker, with several independent collections such as
techbooks and cookbooks.
Map
| Path | Responsibility |
|---|---|
AGENTS.md |
Agent rules; single source of truth |
PRODUCT.md |
Durable product context for the impeccable skill |
docs/specs/, docs/plans/ |
Approved specs and implementation plans |
No source directories exist yet. Add rows here as they appear.
Intended shape
Not yet decided or validated. The pieces the spec has to place:
- A Recoll layer that owns indexing and querying, per collection.
- An HTTP API consumed by both the web UI and the MCP server, so the two never diverge.
- An MCP server exposing search (and likely collection listing) as tools.
- A Docker image that contains Recoll itself, plus compose wiring for document volumes and index storage.
Open design questions
The first spec must answer these. None are settled.
- Collection isolation. Recoll's model is a config directory per index (
RECOLL_CONFDIR). Confirm against Recoll's own docs, then decide: one config dir per collection, and what owns the mapping from collection name to config dir and document root. - Cross-collection search. Allowed at all? If yes, merged ranking across separately-scored indexes is not free — decide before building the UI around it.
- Indexing trigger. Cron inside the container, Recoll's real-time monitor, or API-triggered runs. Affects whether the container needs a long-running process beyond the web server.
- Stack. Unchosen. See
AGENTS.mdCommands for what this host actually has installed. - Auth and exposure. Whether the service authenticates at all, or assumes a reverse proxy does it.
- Result presentation. Recoll returns snippets and can extract/preview documents; decide how much of that the API surfaces, since it drives both the UI and the MCP tool shape.
External dependencies
| Dependency | What breaks without it |
|---|---|
| Recoll (in-container) | All indexing and search. Not installed on the host — see AGENTS.md Rules. |
| Docker + compose | The only supported way to run the service. |
| Document volumes | Nothing to index; collections resolve to empty. |
Invariants
To be established with the first code. Candidates the spec should confirm and then record here: a query never silently spans collections; indexed content is never written into the repository.
Known rough edges
None yet — nothing has been built. Cross-linked backlog: docs/TODO.md.