# 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).