# 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.