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>
This commit is contained in:
2026-03-28 11:53:26 -07:00
commit bc1627915e
36 changed files with 3773 additions and 0 deletions

90
ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,90 @@
# 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:
```sql
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.
### Web UI (session cookie auth)
| 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.