mc/mcq

Files

Kyle Isom bc1627915e Initial implementation of mcq — document reading queue

Single-binary service: push raw markdown via REST/gRPC API, read rendered
HTML through mobile-friendly web UI. MCIAS auth on all endpoints, SQLite
storage, goldmark rendering with GFM and syntax highlighting.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-28 11:53:26 -07:00

2.5 KiB

Raw Blame History

MCQ Architecture

Purpose

MCQ is a document reading queue. Push raw markdown from inside the infrastructure, read rendered HTML on any device via the web UI.

System Context

Push clients (curl, scripts, Claude remote)
    │
    ▼ PUT /v1/documents/{slug}
┌─────────┐     ┌──────────┐
│   MCQ   │────▶│  MCIAS   │  auth validation
│ :8443   │◀────│ :8443    │
└─────────┘     └──────────┘
    │
    ▼ SQLite
┌─────────┐
│ mcq.db  │
└─────────┘

Browser (phone, desktop)
    │
    ▼ GET / → login → reading queue → /d/{slug}
┌─────────┐
│   MCQ   │
│ web UI  │
└─────────┘

Data Model

Single table:

CREATE TABLE documents (
    id        INTEGER PRIMARY KEY,
    slug      TEXT NOT NULL UNIQUE,
    title     TEXT NOT NULL,
    body      TEXT NOT NULL,         -- raw markdown
    pushed_by TEXT NOT NULL,         -- MCIAS username
    pushed_at TEXT NOT NULL,         -- RFC 3339 UTC
    read      INTEGER NOT NULL DEFAULT 0
);

Slug is the identity key. PUT with the same slug replaces content and resets the read flag.

API

REST (Bearer token auth)

Method	Path	Auth	Description
POST	/v1/auth/login	Public	Get bearer token
POST	/v1/auth/logout	Auth	Revoke token
GET	/v1/health	Public	Health check
GET	/v1/documents	Auth	List all documents
GET	/v1/documents/{slug}	Auth	Get document
PUT	/v1/documents/{slug}	Auth	Create or update
DELETE	/v1/documents/{slug}	Auth	Remove document
POST	/v1/documents/{slug}/read	Auth	Mark read
POST	/v1/documents/{slug}/unread	Auth	Mark unread

gRPC

DocumentService, AuthService, AdminService — mirrors REST exactly.

Path	Description
/login	MCIAS login form
/	Document list (queue)
/d/{slug}	Rendered markdown reader

Security

MCIAS auth on all endpoints (REST: Bearer, Web: session cookie, gRPC: interceptor)
CSRF double-submit cookies on all web mutations
TLS 1.3 minimum
Default-deny on unmapped gRPC methods

Rendering

Goldmark with GFM extensions, Chroma syntax highlighting, auto heading IDs. Markdown stored raw in SQLite, rendered to HTML on each page view.

2.5 KiB Raw Blame History