Kyle Isom
bc1627915e
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>
91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# 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.
|