Scaffold pal-e-docs service (SQLite + cluster knowledge API) #1

New issue

Closed

opened 2026-02-23 18:23:53 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-02-23 18:23:53 +00:00

Owner

Goal

Scaffold pal-e-docs as the platform's knowledge service — SQLite-backed, queryable by all services and AI agents.

Architecture

SQLite on PVC, not Postgres. Repo contains schema + app code only. Docs accumulate in .db file on PersistentVolumeClaim. Repo never grows as content is added.

WAL mode for concurrent reads during writes
Alembic migrations for schema evolution
Backup = file copy (Litestream later)
No postgres Deployment/Service/PVC/secrets

Platform Role

pal-e-docs is the cluster's brain. Other services and AI agents query its API:

GET /notes?tags=auth,sop → platform SOPs about auth
GET /projects/basketball-api/notes → all basketball-api decisions
GET /notes/{slug} → specific doc with HTML content

Minimizes token cost for AI (targeted queries vs crawling files). Same data serves human-readable frontend.

Data Model

Project: id, name, slug, platform (github/forgejo/local), repo_url, timestamps
Note: id, title, slug, html_content, project_id (nullable), is_public, timestamps
Tag: id, name (unique)
NoteTag: note_id, tag_id (many-to-many)
NoteLink: source_note_id, target_note_id (cross-links)
NoteRevision: id, note_id, html_content, revised_by (PR URL), revised_at, revision_number

IDs are integers (SQLite autoincrement), not UUIDs.

API Endpoints

GET /projects, GET /projects/{slug}/notes
GET /notes?tags=..., GET /notes/{slug}, POST/PUT/DELETE /notes/{slug}
GET /notes/{slug}/links, GET /notes/{slug}/revisions
GET /tags
GET /healthz, GET /metrics

k8s Manifests (no postgres)

kustomization.yaml, deployment.yaml, service.yaml, servicemonitor.yaml, pvc.yaml
PVC mounted at /data/pal-e-docs.db
No namespace in manifests (ArgoCD controls placement)

var.services entry

pal-e-docs = {
  forgejo_repo = "forgejo_admin/pal-e-docs"
  image_repo   = "pal-e-docs/api"
  port         = 8000
  funnel       = true
}

Depends on

pal-e-auth package (forgejo_admin/pal-e-auth#1)
tofu apply for namespace + Harbor project

## Goal Scaffold pal-e-docs as the platform's knowledge service — SQLite-backed, queryable by all services and AI agents. ## Architecture **SQLite on PVC**, not Postgres. Repo contains schema + app code only. Docs accumulate in `.db` file on PersistentVolumeClaim. Repo never grows as content is added. - WAL mode for concurrent reads during writes - Alembic migrations for schema evolution - Backup = file copy (Litestream later) - No postgres Deployment/Service/PVC/secrets ## Platform Role pal-e-docs is the cluster's brain. Other services and AI agents query its API: - `GET /notes?tags=auth,sop` → platform SOPs about auth - `GET /projects/basketball-api/notes` → all basketball-api decisions - `GET /notes/{slug}` → specific doc with HTML content Minimizes token cost for AI (targeted queries vs crawling files). Same data serves human-readable frontend. ## Data Model - **Project**: id, name, slug, platform (github/forgejo/local), repo_url, timestamps - **Note**: id, title, slug, html_content, project_id (nullable), is_public, timestamps - **Tag**: id, name (unique) - **NoteTag**: note_id, tag_id (many-to-many) - **NoteLink**: source_note_id, target_note_id (cross-links) - **NoteRevision**: id, note_id, html_content, revised_by (PR URL), revised_at, revision_number IDs are integers (SQLite autoincrement), not UUIDs. ## API Endpoints - GET /projects, GET /projects/{slug}/notes - GET /notes?tags=..., GET /notes/{slug}, POST/PUT/DELETE /notes/{slug} - GET /notes/{slug}/links, GET /notes/{slug}/revisions - GET /tags - GET /healthz, GET /metrics ## k8s Manifests (no postgres) - kustomization.yaml, deployment.yaml, service.yaml, servicemonitor.yaml, pvc.yaml - PVC mounted at /data/pal-e-docs.db - No namespace in manifests (ArgoCD controls placement) ## var.services entry ```hcl pal-e-docs = { forgejo_repo = "forgejo_admin/pal-e-docs" image_repo = "pal-e-docs/api" port = 8000 funnel = true } ``` ## Depends on - pal-e-auth package (forgejo_admin/pal-e-auth#1) - tofu apply for namespace + Harbor project