pablan/README.md

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
• 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+.

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:

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/.

Documentation

roadmap.md	feature backlog: what's built and what's next, as a rebuild manual
architecture.md	deployment model, backend/frontend structure, mode engine
data-model.md	tables, permission model, hybrid retrieval, GDPR defaults
api-protocol.md	REST + SSE contract
authoring-templates.md	declarative Markdown-skeleton template format for capture
i18n.md	message conventions, locale resolution, what stays untranslated
decisions.md	ADR-style decision log
notes.md	durable implementation learnings — calibrations, gotchas, rationale
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 (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.