pal-e-api — Documentation & Kanban Platform API

FastAPI backend powering a custom documentation platform with block-structured content, kanban boards, and semantic search.

Built to serve both human users (via a SvelteKit frontend) and AI agents (via an MCP server), this API is the single source of truth for SOPs, architecture decisions, project documentation, and work tracking across a multi-repo platform.

Tech Stack

Layer	Technology
Framework	FastAPI + Uvicorn
ORM	SQLAlchemy 2.0 (declarative mapped columns)
Migrations	Alembic (22 migrations)
Database	PostgreSQL via CNPG (CloudNativePG) on Kubernetes
Search	pgvector embeddings + tsvector full-text, fused via Reciprocal Rank Fusion
Auth	JWT with role-based access (public read, admin write)
Monitoring	Prometheus metrics via prometheus-fastapi-instrumentator
CI/CD	Woodpecker CI, Harbor registry, ArgoCD GitOps
Tests	685+ tests, pytest

Key Features

Block-first content model. Notes are composed of ordered blocks (headings, paragraphs, code, etc.) stored as structured JSON. Blocks are independently addressable by anchor ID, support pgvector embeddings for semantic search, and compile into cached HTML pages with auto-generated tables of contents.

Kanban boards with full lifecycle. Board items flow through eight columns (backlog, todo, next_up, in_progress, qa, needs_approval, validation, done). Items carry typed labels, Forgejo issue URLs, and position ordering. Boards are project-scoped with one board per project.

Forgejo issue sync. A built-in Forgejo client synchronizes board items with Forgejo issues, keeping the kanban board and issue tracker in lockstep without manual updates.

Hybrid semantic search. Combines pgvector cosine similarity (2560-dim embeddings) with PostgreSQL tsvector keyword search using Reciprocal Rank Fusion (RRF). A background embedding worker processes blocks asynchronously.

MCP server integration. The API is consumed by a Model Context Protocol server, giving AI coding agents direct read/write access to documentation, boards, and search — enabling agents that start every session with full platform context.

Note graph. Bidirectional note links (zettelkasten-style), parent-child hierarchies, tag intersection queries, and revision history with provenance tracking.

API Surface

47 endpoints across 8 route modules:

Module	Scope
notes	CRUD, search, tag filtering, pagination, activity feeds
blocks	Block CRUD, compiled page retrieval, table of contents
boards	Board and board item management, bulk moves, column transitions
projects	Project CRUD with nested note and repo listings
links	Bidirectional note link management
repos	Repository registry (platform, URL, status, project association)
tags	Tag listing and note-tag associations
health	Health check and Prometheus metrics

Public notes are readable without authentication. All write operations require an admin JWT.

Data Model

Project ──< Note ──< Block
  │          │  ╰──< NoteRevision
  │          │  ╰──< NoteTag >── Tag
  │          │  ╰──< NoteLink (bidirectional)
  │          ╰──── CompiledPage
  ╰──< Repo
  ╰──── Board ──< BoardItem

• 12 models: User, Project, Repo, Note, Tag, NoteTag, NoteLink, NoteRevision, Block, CompiledPage, Board, BoardItem
• Block embeddings: 2560-dimensional vectors stored via pgvector, with async worker for background processing
• Board columns: 8-stage kanban (backlog through done), typed items (issue, repo, project, plan, phase, todo)

Project Structure

src/pal_e_docs/
  main.py              # FastAPI app, router registration, lifespan
  models.py            # SQLAlchemy 2.0 models (12 tables)
  schemas.py           # Pydantic request/response schemas
  database.py          # Engine and session configuration
  config.py            # Settings via pydantic-settings
  auth.py              # JWT auth and password hashing
  embedding_worker.py  # Background pgvector embedding processor
  routes/              # 8 route modules (47 endpoints)
  services/            # Forgejo client, hybrid search, template renderer
  blocks/              # Block parser, compiler, note-block sync
alembic/               # 22 database migrations
k8s/                   # Kustomize manifests (deployment, service, servicemonitor)
scripts/               # Data migration utilities
tests/                 # 685+ tests across 29 test modules

Development

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Run locally
python -m pal_e_docs.main

Related Repositories

Repository	Role
pal-e-app	SvelteKit frontend consuming this API
pal-e-docs-sdk	Python SDK for programmatic API access
pal-e-mcp	MCP server exposing API to AI agents
pal-e-platform	Infrastructure bootstrap (k3s, Tailscale, CI/CD)
pal-e-deployments	Kustomize overlays for ArgoCD GitOps