Pablan, as it stands

Self-hosted knowledge management for SMEs: a split-screen Markdown editor whose sections an LLM refines while you write, and RAG question answering over the documents that result. FastAPI + Postgres/pgvector on the back, SvelteKit on the front, everything OpenAI-compatible and self-hostable. Squashed into a single commit; the development history stays local. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CA43ZJda8Rbp2hKXNy8f6b
2026-09-04 09:21:37 +02:00
parent 68d3a43191
commit 784b76baf7
346 changed files with 43430 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Pablan
+
+Self-hosted knowledge management for SMEs. Employees capture knowledge by
+writing Markdown directly into a document, with an LLM editor that matures the
+section at the cursor as they write (onboarding, offboarding, project debriefs
+and more, started from templates); the results are stored as Markdown documents
+and questions about the knowledge base are answered via RAG. Everything runs on
+your own infrastructure. The interface ships in German and English.
+
+The problem it solves: knowledge leaves the company when employees do, and
+departments solve problems in isolation. Pablan makes writing tacit knowledge
+down quick and makes it searchable, with permission filtering **before** the
+LLM sees anything, drafts that stay private until their author publishes them,
+and GDPR-friendly retention defaults.
+
+## Stack
+
+- **Backend** — Python 3.12, FastAPI (async), SQLAlchemy 2.0 + Alembic, managed with [uv](https://docs.astral.sh/uv/)
+- **Database** — PostgreSQL + pgvector: relational data, documents, embeddings, full-text (hybrid search), jobs and sessions in one DB
+- **Frontend** — SvelteKit (Svelte 5) + TypeScript + Tailwind, own components on Bits UI
+- **LLM** — any OpenAI-compatible endpoint (llama.cpp locally, cloud APIs in prod); three independently configured model roles: chat / utility / embedding
+- **Deployment** — Docker Compose: postgres, backend, frontend, Caddy
+
+## Development
+
+Prerequisites: Docker, uv, Node 22+.
+
+```sh
+cp .env.example .env   # set DB password and LLM endpoints
+make dev               # postgres in docker, backend + frontend native with hot reload
+make migrate           # apply DB migrations
+make seed              # seed dev data
+```
+
+App: <http://localhost:5173> · API: <http://localhost:8000/api>
+
+| Command | |
+|---|---|
+| `make dev` / `make down` | start / stop the dev stack |
+| `make migrate` | apply Alembic migrations |
+| `make seed` | seed dev data |
+| `make types` | regenerate the typed API client from OpenAPI |
+| `make lint` | ruff + prettier + eslint + token contrast check (same as CI) |
+| `make eval` | LLM eval suite against the configured endpoints |
+| `make e2e` | Playwright end-to-end tests |
+
+## Deployment
+
+The customer stack is plain Docker Compose:
+
+```sh
+cp .env.example .env   # set POSTGRES_PASSWORD, PABLAN_DOMAIN, LLM endpoints
+docker compose up -d --build
+```
+
+Caddy terminates TLS for `PABLAN_DOMAIN` automatically and serves frontend and
+API on one origin — config in [`deploy/`](deploy/README.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [roadmap.md](docs/roadmap.md) | feature backlog: what's built and what's next, as a rebuild manual |
+| [architecture.md](docs/architecture.md) | deployment model, backend/frontend structure, mode engine |
+| [data-model.md](docs/data-model.md) | tables, permission model, hybrid retrieval, GDPR defaults |
+| [api-protocol.md](docs/api-protocol.md) | REST + SSE contract |
+| [authoring-templates.md](docs/authoring-templates.md) | declarative Markdown-skeleton template format for capture |
+| [i18n.md](docs/i18n.md) | message conventions, locale resolution, what stays untranslated |
+| [decisions.md](docs/decisions.md) | ADR-style decision log |
+| [notes.md](docs/notes.md) | durable implementation learnings — calibrations, gotchas, rationale |
+| [licensing.md](docs/licensing.md) | Fair Source licensing model |
+
+## License
+
+Pablan is **Fair Source**: the core is licensed under the
+[Functional Source License 1.1 with Apache 2.0 future grant](LICENSE)
+(FSL-1.1-ALv2) — free to read, audit, self-host and use internally; each
+release automatically becomes Apache 2.0 two years after publication. The
+`ee/` directory contains proprietary Enterprise modules under a
+[separate license](ee/LICENSE).