24 lines
1.9 KiB
Markdown
24 lines
1.9 KiB
Markdown
# ADR-001: Backend language and framework
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-08-02
|
|
|
|
## Context
|
|
|
|
The Backend API (see founding strategy, Section 3) is the single source of domain logic for the whole platform: it orchestrates the Knowledge Agent, the Execution Guard, and every integration connector. It needs to be comfortable talking to Qdrant, Postgres, Redis, and local/cloud LLM providers, and needs to be maintainable by a single developer over a period of years.
|
|
|
|
The existing AI stack (Ollama, Qdrant tooling, most LLM/RAG libraries) is Python-centric. Alternatives considered: Go (excellent for infra tooling, but a weaker ecosystem for RAG/embedding work and a steeper day-to-day lift for solo AI-focused development), TypeScript/Node (strong for the n8n/webhook side of things, but would mean maintaining two primary languages across backend and glue layers).
|
|
|
|
## Decision
|
|
|
|
The Backend API is built in **Python**, using **FastAPI**.
|
|
|
|
FastAPI gives us API-first development for free (automatic OpenAPI schema generation, which keeps `docs/api/` honest), async support for talking to multiple I/O-bound systems (Qdrant, Postgres, Docker/Proxmox APIs) without extra ceremony, and direct access to the Python AI/RAG ecosystem the rest of the stack already lives in.
|
|
|
|
## Consequences
|
|
|
|
- One primary language across backend, agents, and integrations — reduces context-switching for a solo developer.
|
|
- n8n workflows remain thin glue (per founding strategy, Section 1.2) calling this API; language choice here doesn't constrain n8n.
|
|
- We accept Python's weaker raw performance vs. Go for CPU-bound work — acceptable, since this platform is I/O-bound (API calls, DB queries, LLM calls), not compute-bound.
|
|
- Revisit only if a specific component (e.g. a high-throughput execution guard under heavy load) demonstrably needs a different runtime — not a whole-platform decision to reopen lightly.
|