feat: add standards wiki, MCP registry, and app template

This commit is contained in:
2026-10-11 22:09:30 +05:30
parent 1ef2efbeda
commit 1208945e1d
155 changed files with 24512 additions and 7 deletions

View File

@@ -0,0 +1,8 @@
{
"module": "overview",
"content": {
"path": "overview",
"docstring": "# Overview\n\n## Summary\n\nThe blueprint is a **hexagonal (ports and adapters) application** with a\n**spec-first** web edge and a **single composition root**. It favors explicit\nwiring over implicit magic, and it prefers existing internal libraries over\nhand-written infrastructure.\n\n---\n\n## The three layers\n\n```\ninterfaces/ ← HTTP edge: thin handlers bound to an OpenAPI operationId\ndomain/ ← business core: models, ports (interfaces), services, orchestrators\ninfra/ ← adapters: databases, caches, external clients, hardware\n```\n\nPlus two optional layers:\n\n```\npipelines/ ← data-driven transformation graphs (extraction, enrichment)\nscripts/ ← operator scripts that reuse the composition root\n```\n\n## Core principles\n\n1. **One-way dependencies.** `interfaces -> domain -> infra` is allowed;\n the reverse is forbidden. The domain never imports a framework it does not\n own.\n2. **Ports in the domain, adapters in infra.** A service depends on an\n abstract port; the composition root injects a concrete adapter.\n3. **One composition root.** Nothing constructs its own dependencies. All\n wiring lives in one module (`init.py`) and is exposed as a flat resource\n registry.\n4. **Spec-first.** The HTTP contract is declared in an OpenAPI document. Route\n handlers are looked up by `operationId`. There are no decorator routers.\n5. **Reuse the libraries.** Pipeline orchestration, DI, Mongo repositories,\n ingestion, auth, and docs are provided by internal libraries. Do not\n reimplement them — see the library registry.\n6. **Explicit state machines.** Long-running work moves through explicit,\n durable statuses and can pause for human input.\n\n## Runtime processes\n\nA standard app may run as up to three processes that share the same\ncomposition root:\n\n| Process | Entry point | Responsibility |\n|---|---|---|\n| API | `main.py` | serve HTTP; start/stop resources via lifespan |\n| Worker | `worker.py` | poll durable jobs, run pipelines, publish progress |\n| Scripts | `python -m scripts.<name>` | one-shot operator tasks |\n",
"objects": {}
}
}