# JustAPI Documentation Site — Production-Grade Build Plan > **Goal:** Build a comprehensive, production-grade documentation site (Astro + Starlight) covering every aspect of the JustAPI runtime — matching the depth, polish, and discoverability of FastAPI, Next.js, and Django docs. > > **Current state (2026-07-24):** `docs_site/` exists with Astro + Starlight but has only 10 pages covering 20% of the framework surface. `docs/` has 7 raw markdown files capturing the handbook, API reference, security, and migration guide. The full codebase has **5 Rust crates**, **~40 public modules**, **33 benchmark scripts**, **12 examples**, **13 test files**, **8 fuzz targets**, **5 cloud deployment guides**, **Helm chart**, **Docker setup**, and **agent-native demo**. --- ## Phase 0: Site Infrastructure & Design System ### 0.1 Framework & Theme | Item | Current | Target | |---|---|---| | SSG framework | Astro 7 + Starlight 0.41 | Astro 7 + Starlight 0.41 (upgrade if newer) | | Theme colors | Purple accent (`#8B5CF6`) | Keep — already distinctive. Add light/dark mode refinement | | Custom CSS | `src/styles/custom.css` (34 lines) | Expand to full design system | | Logo | `src/assets/logo.svg` (bolt/gradient) | Keep — refine for docs page prominence | | Font | Default Starlight | Add system font stack + optional mono for code | | Search | Starlight built-in (Pagefind) | Already works — configure pagefind for full-text + section search | ### 0.2 Navigation Architecture Current sidebar only has 2 autogenerated sections. Replace with explicit, hierarchical navigation: ``` Getting Started [existing, expand] ├── Overview & Philosophy ✓ exists ├── Installation ✓ exists ├── First Steps ✓ exists ├── CLI Project Scaffolder ✓ exists └── Migrating from FastAPI ✗ missing (exists in docs/) Tutorials ✗ missing ├── Hello World in 2 Minutes ✗ missing ├── Path & Query Parameters ✓ exists (path-params.md) ├── Request Body & Validation ✗ missing ├── Dependency Injection ✗ missing ├── Middleware ✗ missing ├── Error Handling ✗ missing ├── File Uploads ✗ missing ├── WebSockets & SSE ✗ missing ├── Database Integration ✓ exists (databases.md) └── Background Tasks ✗ missing API Reference ✗ missing ├── JustAPIApp ✗ missing ├── Routing (GET/POST/PUT/...)✗ missing ├── APIRouter ✗ missing ├── Dependency Injection ✗ missing ├── Request Object ✗ missing ├── Response Classes ✗ missing ├── Exceptions & Error Handling ✗ missing ├── Schema & Validation ✗ missing ├── WebSockets ✗ missing ├── Background Tasks ✗ missing ├── Scheduler ✗ missing ├── Testing Client ✗ missing └── Plugins ✗ missing Advanced Guides ✗ missing ├── Zero-GIL Architecture ✓ exists ├── Rust Core Deep Dive ✗ missing ├── FFI & PyO3 Safety ✗ missing ├── Native Fast Path ✗ missing ├── Multi-Protocol APIs ✗ missing ├── Agent/Session System ✗ missing ├── Streaming Output ✗ missing └── Performance Tuning ✗ missing Deployment Guides ✗ missing ├── Docker & Docker Compose ✗ missing ├── Kubernetes / Helm ✗ missing ├── Cloudflare Pages ✓ exists ├── Google Cloud (GKE) ✗ missing (exists in deploy/) ├── Amazon (EKS) ✗ missing (exists in deploy/) ├── Azure (AKS) ✗ missing (exists in deploy/) ├── Fly.io ✗ missing (exists in deploy/) └── Railway ✗ missing (exists in deploy/) Security ✗ missing ├── Security Policy ✗ missing (exists in docs/) ├── OWASP Compliance Checklist ✗ missing (exists in docs/) ├── Penetration Test Guide ✗ missing (exists in docs/) └── Secure Configuration ✗ missing Observability ✗ missing ├── Metrics & Monitoring ✗ missing ├── OpenTelemetry Tracing ✗ missing ├── Structured Logging ✗ missing └── Health Checks ✗ missing Reference ✗ missing ├── CLI Reference ✗ missing ├── Configuration Reference ✗ missing ├── Release Notes ✓ exists (release-notes.md) ├── Changelog ✗ missing └── Glossary ✗ missing Contributing ✗ missing ├── Development Setup ✗ missing ├── Coding Standards ✗ missing ├── Testing Guide ✗ missing ├── Benchmarking Guide ✗ missing └── Documentation Guide ✗ missing ``` ### 0.3 SEO & Performance - Add sitemap (`@astrojs/sitemap`) - Add OpenGraph + Twitter card meta tags to every page - Configure canonical URLs - Enable Pagefind full-text search with section headings - Add 301 redirects for old `docs/*.md` URLs - Add RSS feed for release notes (`@astrojs/rss`) - Lighthouse target: 100/100 all categories --- ## Phase 1: Getting Started (5 pages — 1 new, 4 enhance existing) ### 1.1 Overview & Core Philosophy ✓ (enhance) **Existing:** `getting-started/overview.md` (minimal, 2 sections) **Enhance:** - Add architecture diagram (Mermaid) - Add performance comparison table from BENCHMARKS.md - Add feature comparison matrix vs FastAPI / Robyn / Granian - Add "Who is this for?" audience section - Add system requirements (Python 3.11+, Rust 1.85+) ### 1.2 Installation ✓ (enhance) **Existing:** `getting-started/installation.md` **Enhance:** - Add troubleshooting section for common install failures - Add platform-specific notes (Windows, macOS, Linux) - Add Docker installation method - Add `justapi[full]` extras documentation - Add verification steps (`python -c "import justapi; print(justapi.__version__)"`) - Add free-threaded Python 3.13t/3.14t installation notes ### 1.3 First Steps ✓ (enhance) **Existing:** `getting-started/first-steps.md` **Enhance:** - Add step-by-step walkthrough with expected output - Add interactive OpenAPI docs section (Swagger, ReDoc, Scalar) - Add "What's happening under the hood?" callout boxes - Add common gotchas section ### 1.4 CLI Project Scaffolder ✓ (enhance) **Existing:** `getting-started/cli-scaffolder.md` **Enhance:** - Add complete CLI reference for `justapi create` - Add generated project structure documentation - Add screenshots of interactive TUI wizard - Add video/gif of scaffolding flow - Add multi-protocol explanation (when to use REST vs GraphQL vs gRPC vs JSON-RPC) ### 1.5 ✨ NEW: Migrating from FastAPI **Source:** `docs/migrating_from_fastapi.md` **Enhance from existing:** - Add import mapping table (full `fastapi.*` → `justapi.*`) - Add decorator compatibility table - Add middleware migration guide - Add dependency injection migration - Add performance expectations after migration - Add common migration pitfalls - Add side-by-side code comparisons for every feature --- ## Phase 2: Tutorials (11 pages — 1 existing, 10 new) ### 2.1 ✨ NEW: Hello World in 2 Minutes Based on `examples/01_hello_world.py`: - Complete walkthrough from zero to running - Expected terminal output - Testing with curl - Project structure discussion ### 2.2 Path & Query Parameters ✓ (enhance) **Existing:** `tutorial/path-params.md` **Enhance:** - Add query parameters tutorial - Add optional vs required parameters - Add default values - Add type conversion table (int, float, str, bool, UUID, datetime) - Add validation error examples - Based on `examples/02_path_query_params.py` ### 2.3 ✨ NEW: Request Body & Validation Based on `examples/03_request_body.py`: - Pydantic BaseModel usage - Schema validation with `body_schema` parameter - Nested models - Optional fields and defaults - Native fast path (`native=True`) explanation - Request body size limits ### 2.4 ✨ NEW: Dependency Injection Based on `examples/04_dependencies.py`: - `Depends()` usage patterns - Callable dependencies - Class-based dependencies - Shared dependencies across routes - Dependency scoping (request vs route vs global) - Connection pooling pattern ### 2.5 ✨ NEW: Middleware Based on `examples/05_middleware.py`: - `@app.middleware("http")` decorator - Request/response interception - Adding custom headers - CORS middleware configuration - Middleware ordering - Timing and logging middleware patterns - Based on `tests/test_middleware.py` ### 2.6 ✨ NEW: Error Handling Based on `examples/06_error_handling.py`: - `HTTPException` usage - Custom exception handlers - `@app.exception_handler` decorator - Validation error handling - Global vs per-route handlers - Error response format (`{"detail": ...}`) ### 2.7 ✨ NEW: File Uploads Based on `examples/07_file_uploads.py`: - `UploadFile` class - `File()` and `Form()` annotations - Multipart form parsing - Streaming file handling - File size limits - Based on `tests/test_multipart.py` ### 2.8 ✨ NEW: WebSockets & SSE Based on `examples/10_websockets.py` and `tests/test_sse.py`: - `@app.websocket()` decorator - WebSocket lifecycle (accept, receive, send, close) - Server-Sent Events with `StreamingResponse` - `TokenStreamResponse` for validated streaming - Real-time communication patterns ### 2.9 Database Integration ✓ (enhance) **Existing:** `tutorial/databases.md` **Enhance:** - Add SQL (PostgreSQL, MySQL, SQLite) with `app.set_database()` - Add NoSQL (MongoDB, Redis) with direct driver usage - Add analytical (DuckDB, ClickHouse) - Add connection pooling configuration - Add migration workflow - Add transaction management - Add query result handling (`q`, `q1`, `paginate` patterns from `demo_shop`) - Add Rust-native query fast path - Add connection saturation and 503 handling - Based on `crates/justapi-py/src/database.rs`, `crates/justapi-core/src/db/pool.rs` ### 2.10 ✨ NEW: Background Tasks Based on `crates/justapi-py/src/background.rs`: - `BackgroundTasks` usage - Adding tasks during request processing - Task execution model (Tokio background) - Error handling in background tasks - Use cases (email sending, data processing, webhooks) ### 2.11 ✨ NEW: Routing & Sub-routers Based on `examples/08_routers.py`: - `APIRouter` for modular routing - Route prefixes - Tags for OpenAPI grouping - Including routers in main app - Route ordering and conflict resolution --- ## Phase 3: API Reference (13 pages — all new) Source material: `docs/api_reference.md`, `crates/justapi-py/src/lib.rs`, all Python framework code, all Rust public modules. ### 3.1 ✨ NEW: JustAPIApp - Constructor: `JustAPIApp(title, version, description, ...)` - Route decorators: `@app.get`, `@app.post`, `@app.put`, `@app.patch`, `@app.delete` - `@app.websocket`, `@app.middleware`, `@app.exception_handler` - `@app.tool` (MCP tool registration) - `@app.stream_json` (validated streaming) - `app.include_router()`, `app.use()` (plugins) - `app.run()`, `app.graphql()`, `app.enable_sessions()` - `app.set_database()`, `app.enable_circuit_breaker()`, `app.enable_request_coalescing()` - `app.enable_secure_headers()`, `app.add_cors()` - `app.register_health_check()` - Full parameter reference with types and defaults ### 3.2 ✨ NEW: Routing - `get(path, dependencies)` - `post(path, body_schema, schema, dependencies)` - `put`, `patch`, `delete` — full signatures - Path parameter types and conversion - Route ordering and matching (matchit radix trie) - Route-lookup cache (ADR-064) ### 3.3 ✨ NEW: APIRouter - Constructor: `APIRouter(prefix, tags)` - All route decorators - `include_router()` integration - Router-level middleware - Router-level dependencies ### 3.4 ✨ NEW: Request Object - `Request` class attributes: `method`, `path`, `url`, `headers`, `query_params`, `state` - `request.json()`, `request.body()`, `request.form()` - `request.headers` (Headers class) - `request.query_params` (QueryParams class) - `request.state` (State class) - Zero-copy buffer protocol details ### 3.5 ✨ NEW: Response Classes - `Response(content, status_code, headers)` - `JSONResponse(content)` - `HTMLResponse(content)` - `PlainTextResponse(content)` - `RedirectResponse(url, status_code)` - `StreamingResponse(generator, media_type)` - `TokenStreamResponse` (validated streaming) - `ValidatedStreamResponse` ### 3.6 ✨ NEW: Dependency Injection - `Depends(dependency, use_cache)` - `Path()`, `Query()`, `Header()`, `Cookie()`, `Body()` - `File()`, `Form()` - Callable dependencies - Class dependencies - Global vs route-level dependencies - Dependency caching ### 3.7 ✨ NEW: Exceptions & Error Handling - `HTTPException(status_code, detail, headers)` - `RequestValidationError(errors)` - Exception handler registration - Custom exception classes - Error response format - RFC 9457 structured errors ### 3.8 ✨ NEW: Schema & Validation - `Schema` class (JustAPI native, not Pydantic) - `Field()` constraints (gt, ge, lt, le, min_length, max_length, regex, format, enum, description) - Nested schemas with `$ref`/`$defs` - `native=True` validation in Rust - Pydantic v2 bridge - JSON Schema generation - `validate_value()` function ### 3.9 ✨ NEW: WebSockets - `WebSocket` class - `accept()`, `receive_text()`, `send_text()`, `close()` - `receive_bytes()`, `send_bytes()` - `receive_json()`, `send_json()` - Connection lifecycle - WebSocket state (`WebSocketState`) ### 3.10 ✨ NEW: Background Tasks - `BackgroundTasks` class - `add_task(callable, *args, **kwargs)` - Execution model - Error handling ### 3.11 ✨ NEW: Scheduler - `PyScheduler` class (Rust-native cron scheduler) - Scheduling syntax (cron expressions) - Interval-based scheduling - One-time delayed tasks - UTC-based execution - Based on `crates/justapi-py/src/scheduler.rs` ### 3.12 ✨ NEW: Session (Agent System) - `Session` class - `session.id`, `session.get()`, `session.update()` - Session cookie (`justapi_session`) - Query parameter session ID - Rust-backed durable store - Based on `examples/agent_demo/app.py` ### 3.13 ✨ NEW: Plugin System - Python plugin hooks: `build()`, `on_startup()`, `on_shutdown()` - Rust plugin trait: `Plugin` - Plugin registration with `app.use()` - Plugin lifecycle - Plugin marketplace (PyPI publishing) - Based on `docs/plugins.md`, `crates/justapi-core/src/plugin.rs` ### 3.14 ✨ NEW: Testing Client - `JustAPITestClient` class - Usage patterns for route testing - Async test support - Based on `crates/justapi-py/src/test_client.rs` ### 3.15 ✨ NEW: UploadFile - `UploadFile` class - Properties: `filename`, `content_type`, `file` - Methods: `read()`, `write()`, `seek()`, `close()` - Temporary file management - Size limits ### 3.16 ✨ NEW: Database - `Database` class (Python API) - `app.set_database(url, init_sql, max_connections, request_acquire_timeout, wal, pragmas)` - `app.db.query(sql, params)`, `app.db.execute(sql, params)` - Rust-native `AnyPool` - Supported engines and URLs - Connection pool configuration - Migration system --- ## Phase 4: Advanced Guides (9 pages — 1 existing, 8 new) ### 4.1 Zero-GIL Architecture ✓ (enhance) **Existing:** `advanced/zero-gil-architecture.md` **Enhance:** - Add detailed GIL release lifecycle - Add `py.allow_threads` code examples from Rust - Add free-threading (PEP 703) deep dive - Add GIL pool architecture (`gil_pool.rs`) - Add thread-safety guarantees - Add benchmark comparisons (GIL vs no-GIL) ### 4.2 ✨ NEW: Rust Core Deep Dive Based on `ARCHITECTURE.md` and `crates/justapi-core/src/`: - Server lifecycle (`Server::run()`, `serve()`) - Connection management (Tokio + epoll/io_uring) - TLS termination (rustls) - HTTP parsing (hyper 1.x) - Radix trie routing (matchit) - Middleware chain architecture - Request pipeline (end-to-end flow diagram) - Zero-copy FFI with PyO3 ### 4.3 ✨ NEW: PyO3 & FFI Safety Based on `skills/rust-ffi-safety/SKILL.md`: - GIL acquisition discipline - Buffer protocol for zero-copy - `// SAFETY:` conventions - Send/Sync boundaries with Python objects - Free-threaded Python support - Common FFI pitfalls ### 4.4 ✨ NEW: Native Fast Path Based on `DECISIONS.md` ADR-047, ADR-048: - `native=True` route decorator - 100% Rust execution path - Schema validation in Rust (jsonschema-rs) - Response serialization in Rust (simd-json) - Performance characteristics (724k+ RPS) - When to use native vs Python handler ### 4.5 ✨ NEW: Multi-Protocol APIs Based on `docs/HANDBOOK.md` §6: - REST (OpenAPI 3.1 + Swagger/ReDoc/Scalar) - GraphQL (`app.graphql()`, async-graphql) - gRPC / Protobuf (tonic, prost) - JSON-RPC 2.0 - Protocol selection guide - Multi-protocol architecture patterns ### 4.6 ✨ NEW: Agent System (MCP Tools & Sessions) Based on `examples/agent_demo/app.py`: - `@app.tool` decorator and MCP tool registration - Tool schema inference from type hints - `GET /_system/tools`, `POST /_system/tools/call` - `app.run_mcp_stdio()` for stdio MCP server - Session management (`app.enable_sessions()`) - Agent state persistence pattern ### 4.7 ✨ NEW: Streaming Validated Output Based on `crates/justapi-py/src/native/app.rs`: - `@app.stream_json(path, schema, mode)` - NDJSON mode vs JSON array mode - Rust-side validation per-chunk - Abort-on-invalid semantics - Use cases (LLM streaming, data pipelines, real-time events) ### 4.8 ✨ NEW: Performance Tuning Based on `BENCHMARKS.md`, `skills/benchmark-harness/SKILL.md`, `PRODUCTION.md`: - Worker count tuning (`--workers N`) - Connection pool sizing - Body size limits - Timeout configuration - TLS overhead (10.7%) - K8s overhead (8.4%) - Compression trade-offs - Native fast path optimization - Route-lookup cache - Load-based auto-scaling (`--scale`) ### 4.9 ✨ NEW: Resilience Patterns Based on `docs/HANDBOOK.md` §10: - Circuit breakers (`enable_circuit_breaker`) - Request coalescing (`enable_request_coalescing`) - Bulkhead pattern (max concurrent requests) - Rate limiting (global and per-IP) - Graceful degradation (FallbackMiddleware) - Graceful shutdown (SIGTERM → drain → stop) - Timeout middleware (504 Gateway Timeout) --- ## Phase 5: Deployment (8 pages — 5 existing in deploy/, 3 new) ### 5.1 ✨ NEW: Docker & Docker Compose Based on `Dockerfile` and `docker-compose.yml`: - Multi-stage Docker build - Production image optimization - Docker Compose for local development - Environment variables reference - Health checks configuration - Volume mounts and persistence ### 5.2 ✨ NEW: Kubernetes & Helm Based on `helm/justapi/`: - Helm chart structure - Values reference - Deployment configuration - HPA autoscaling - Ingress with TLS (cert-manager) - Secrets management - Liveness/readiness probes - ServiceAccount and security context ### 5.3 Cloudflare Pages ✓ (enhance) **Existing:** `deployment/cloudflare-pages.md` **Enhance:** Add wrangler configuration details ### 5.4 ✨ NEW: Google Cloud (GKE) Based on `deploy/clouds/gke.md`: - Cluster creation - Ingress setup - cert-manager - Deploy with Helm ### 5.5 ✨ NEW: Amazon EKS Based on `deploy/clouds/eks.md`: - Cluster creation with eksctl - AWS Load Balancer Controller - ECR image registry - Deploy with Helm (ALB ingress) ### 5.6 ✨ NEW: Azure AKS Based on `deploy/clouds/aks.md`: - Cluster creation - NGINX Ingress Controller - cert-manager - ACR integration - Deploy with Helm ### 5.7 ✨ NEW: Fly.io Based on `deploy/clouds/flyio.md`: - fly.toml configuration - Launch and scale - Fly Postgres attachment ### 5.8 ✨ NEW: Railway Based on `deploy/clouds/railway.md`: - Project setup - Environment configuration - Deployment workflow ### 5.9 ✨ NEW: Production Checklist Based on `PRODUCTION.md`: - Build configuration (release mode, panic=abort) - Process supervision (systemd, K8s, Docker restart) - TLS termination (edge proxy vs native) - Request body size limits - Security headers - Health/readiness/liveness endpoints - Metrics scraping (Prometheus) - Connection and timeout tuning - Graceful shutdown verification - Pre-flight checklist (interactive checklist page) --- ## Phase 6: Security (4 pages — all new, based on docs/security/) ### 6.1 ✨ NEW: Security Policy Based on `docs/security/policy.md`: - Supported versions table - Vulnerability reporting process - Response timeline - Scope (in-scope/out-of-scope) - Hall of Fame ### 6.2 ✨ NEW: OWASP Top 10 Compliance Based on `docs/security/owasp-checklist.md`: - A01-A10 coverage - Implemented vs planned features - Configuration guides for each control - CI/CD security checks - Supply chain security (cargo audit, cargo deny, Dependabot) ### 6.3 ✨ NEW: Penetration Testing Guide Based on `docs/security/pentest-guide.md`: - Attack surface map - Test scenarios (auth, injection, session, rate limiting, TLS, info disclosure) - Security headers reference - Fuzz testing workflow (cargo-fuzz targets) - Supply chain verification - Tool list with commands - CVSS scoring and report template ### 6.4 ✨ NEW: Secure Configuration Guide Based on `PRODUCTION.md` §6, `docs/HANDBOOK.md` §10: - Secure headers (`enable_secure_headers`) - CORS configuration (default-deny) - Rate limiting configuration - JWT signing and verification - Secrets management - Body size limits (DoS hardening) - TLS configuration --- ## Phase 7: Observability (4 pages — all new) ### 7.1 ✨ NEW: Metrics & Monitoring Based on `crates/justapi-core/src/metrics.rs`: - Prometheus endpoint (`/metrics`) - Available metrics: request count, latency histograms, connection count, error ratios - Prometheus scrape configuration - Grafana dashboard setup - Alerting rules - Based on ADR-012, ADR-024 ### 7.2 ✨ NEW: OpenTelemetry Tracing Based on `crates/justapi-core/src/tracing_setup.rs`, `crates/justapi-core/src/trace_context.rs`: - OTLP gRPC span exporter - Distributed tracing setup - Span attributes and context propagation - Jaeger integration (`docker-compose.otel.yml`) - Tracing across PyO3 boundary - Based on ADR-025 ### 7.3 ✨ NEW: Structured Logging Based on `crates/justapi-py/src/logging.rs`: - JSON log format - Log levels configuration (`RUST_LOG`) - tracing-subscriber setup - Log aggregation (ELK, Loki) - Avoiding PII in production logs ### 7.4 ✨ NEW: Health Checks Based on `crates/justapi-core/src/health.rs`: - `/health`, `/live`, `/ready` endpoints - `register_health_check()` API - Custom health check functions - DB connectivity checks - Downstream dependency checks - Kubernetes probe configuration --- ## Phase 8: Reference (6 pages — 1 existing, 5 new) ### 8.1 ✨ NEW: CLI Reference Based on `crates/justapi-cli/src/main.rs`: - `justapi serve` — dev server with hot-reload, workers, TLS, auto-scaling - `justapi create` — project scaffolder with --db, --api-type - `justapi db` — database commands (migrate, rollback, seed, list, reset, inspect) - `justapi routes` — route visualization - `justapi doctor` — system diagnostics - `justapi gen` — OpenAPI spec generation, client codegen - `justapi check` — configuration validation - `justapi new` — new project - `justapi profile` — handler profiling - Full flag/option reference for each subcommand ### 8.2 ✨ NEW: Configuration Reference - Environment variables (`RUST_LOG`, `DATABASE_URL`, `REDIS_URL`, etc.) - `JustAPIApp()` constructor parameters - `app.run()` parameters - `app.set_database()` parameters - Server configuration (timeouts, body limits, workers, scaling) - Feature flags (tls, ws, compression, opentelemetry, db, inference) ### 8.3 Release Notes ✓ (enhance) **Existing:** `reference/release-notes.md` **Enhance:** - Add full changelog from REVISION_LOG.md - Add upgrade guides between versions - Add deprecation notices - Add migration scripts for breaking changes ### 8.4 ✨ NEW: Decision Records (ADR) Index Based on `DECISIONS.md`: - Index of all 75+ ADRs - Searchable by category (architecture, security, performance, deployment) - Links to detailed explanations - Key decisions that new contributors should understand ### 8.5 ✨ NEW: Error Code Reference Based on `crates/justapi-core/src/error_catalog.rs` and `crates/justapi-cli/src/main.rs`: - Error code catalog (E001, E002, ...) - Error message format - Troubleshooting guide for each error - Common fixes ### 8.6 ✨ NEW: Glossary - Key terms: GIL, PyO3, Tokio, Hyper, matchit, native fast path, ASGI, MCP, SSE - Architecture terms: Zero-copy FFI, radix trie, bulkhead, circuit breaker - Deployment terms: HPA, Helm, mTLS, OTLP --- ## Phase 9: Contributing Guide (5 pages — all new) ### 9.1 ✨ NEW: Development Setup Based on `CONTRIBUTING.md`: - Repository clone and structure - Rust toolchain setup (rustup, nightly for fuzzing) - Python virtual environment - Building with maturin - Running tests (Rust + Python) - Code editor setup (rust-analyzer, pyright) ### 9.2 ✨ NEW: Coding Standards Based on `AGENTS.md`, `CONTRIBUTING.md`: - Rust-first mandate (what goes in Rust vs Python) - Commit message format (`: `) - Branch naming (`phase-N/`) - `unsafe` block requirements (`// SAFETY:`) - Error handling conventions (anyhow vs thiserror) - Public API documentation requirements ### 9.3 ✨ NEW: Testing Guide Based on all test files: - Running `cargo test --workspace` - Running `pytest` for Python tests - Miri validation (`cargo miri test`) - Writing test client tests (`JustAPITestClient`) - Writing integration tests (HTTP server + test client) - Snapshot testing patterns - Test file naming conventions - Property-based testing (proptest) ### 9.4 ✨ NEW: Benchmarking Guide Based on `skills/benchmark-harness/SKILL.md`, `BENCHMARKS.md`: - Benchmark harness setup (`justapi-bench`, `oha`) - Hardware fixture documentation - Benchmark protocol (warmup, runs, reporting) - Workload types and their purposes - Interpreting results (p50, p95, p99, RPS) - Regression gate (5% p99 threshold) - Adding new benchmarks ### 9.5 ✨ NEW: Documentation Guide - How docs_site is built (Astro + Starlight) - Adding new pages - Sidebar configuration - Code block conventions - Image and diagram guidelines - Previewing docs locally (`npm run dev`) - Documentation review process --- ## Phase 10: AI/Inference Documentation (4 pages — all new) ### 10.1 ✨ NEW: Inference Engine Overview Based on `crates/justapi-inference/`: - Architecture (Engine, Scheduler, Gateway, Control Plane) - KV Cache (PagedAttention, BlockPool) - Prefix Cache (RadixPrefixCache) - Speculative Decoding - Disaggregated Prefill/Decode (PdScheduler) - Current status (frozen per ADR-067, target 2.0.8) ### 10.2 ✨ NEW: LLM Serving API Based on `crates/justapi-inference/src/openai.rs`: - OpenAI-compatible chat completions API - Streaming support - Embeddings API - Model management (list, load, unload) - Sampling parameters ### 10.3 ✨ NEW: GPU & CUDA Configuration Based on `crates/justapi-bench/src/gpu_bench.rs`: - CUDA setup with Candle - GPU memory management - Multi-GPU sharding - Benchmark methodology ### 10.4 ✨ NEW: Scheduling & Batching Based on `crates/justapi-inference/src/scheduler.rs`, `pd.rs`: - Continuous batching - Prefill/decode disaggregation - Priority scheduling - Fairness and QoS - Queue management --- ## Phase 11: Examples & Code Playground (1 page — new) ### 11.1 ✨ NEW: Examples Gallery Based on all 12 `examples/*.py` files + `demo_shop/`: - Categorized example index - Each example with: description, code, expected output, key concepts - Runnable code blocks (interactive playground if feasible) - Examples: 1. Hello World (01_hello_world.py) 2. Path & Query Params (02_path_query_params.py) 3. Request Body (03_request_body.py) 4. Dependencies (04_dependencies.py) 5. Middleware (05_middleware.py) 6. Error Handling (06_error_handling.py) 7. File Uploads (07_file_uploads.py) 8. Routers (08_routers.py) 9. DB Integration (09_db_integration.py) 10. WebSockets (10_websockets.py) 11. Plugin System (plugin_cache.py) 12. Agent Demo (agent_demo/) 13. E-Commerce Shop (demo_shop/ — 23 endpoints) --- ## Phase 12: Technical Implementation Tasks ### 12.1 Content Migration - [ ] Convert `docs/HANDBOOK.md` (498 lines) into ~15 structured pages - [ ] Convert `docs/api_reference.md` (101 lines) into expanded reference pages - [ ] Convert `docs/plugins.md` (105 lines) into plugin guide + reference - [ ] Convert `docs/migrating_from_fastapi.md` (41 lines) into enhanced migration guide - [ ] Convert `docs/security/policy.md` (55 lines) + `owasp-checklist.md` (86 lines) + `pentest-guide.md` (143 lines) into security section - [ ] Convert `deploy/clouds/*.md` (5 files) into deployment section - [ ] Convert `PRODUCTION.md` (207 lines) into production checklist - [ ] Convert `ARCHITECTURE.md` (129 lines) into architecture deep-dive - [ ] Convert `CONTRIBUTING.md` (87 lines) into contributing section - [ ] Extract API docs from all `crates/*/src/` public items ### 12.2 Automation & Tooling - [ ] Add `@astrojs/sitemap` for SEO - [ ] Add `@astrojs/rss` for release notes feed - [ ] Configure Pagefind for full-text search across all pages - [ ] Add Mermaid.js support for architecture diagrams - [ ] Add OpenGraph image generation - [ ] Set up CI/CD: build docs site on PR + deploy on merge to main - [ ] Set up Cloudflare Pages auto-deploy from GitHub (currently configured) - [ ] Add broken link checker in CI - [ ] Add spell checker in CI (cspell) ### 12.3 Design Enhancements - [ ] Expand `src/styles/custom.css` to full design system - [ ] Create reusable components: BenchTable, CodeExample, ArchitectureDiagram, FeatureCard - [ ] Add interactive benchmark comparison widget (from BENCHMARKS.md data) - [ ] Add dark/light mode polish - [ ] Add responsive design for mobile - [ ] Add copy-to-clipboard for code blocks ### 12.4 Quality Assurance - [ ] All pages: frontmatter with title, description, sidebar label - [ ] All code examples: syntax-highlighted and tested - [ ] All links: verified working - [ ] Lighthouse audit: target 100/100 - [ ] Accessibility audit: WCAG 2.1 AA - [ ] Mobile-responsive review - [ ] Print layout review --- ## Phase 13: Content Audit & Gap Analysis ### Pages That Exist (10) | Page | Location | Quality | |---|---|---| | index.mdx (splash) | `docs/` | Good | | getting-started/overview.md | `docs_site/` | Minimal | | getting-started/installation.md | `docs_site/` | Good | | getting-started/first-steps.md | `docs_site/` | Good | | getting-started/cli-scaffolder.md | `docs_site/` | Good | | tutorial/path-params.md | `docs_site/` | Good | | tutorial/databases.md | `docs_site/` | Minimal | | deployment/cloudflare-pages.md | `docs_site/` | Good | | advanced/zero-gil-architecture.md | `docs_site/` | Good | | reference/release-notes.md | `docs_site/` | Good | ### Content in Root `docs/` Not Yet in `docs_site/` (5) - `docs/HANDBOOK.md` (498 lines — massive comprehensive handbook) - `docs/api_reference.md` (101 lines — API listing) - `docs/migrating_from_fastapi.md` (41 lines) - `docs/plugins.md` (105 lines) - `docs/security/*` (3 files, 284 lines total) ### Content in Root `.md` Files Not Yet in `docs_site/` (8) - `ARCHITECTURE.md` (129 lines) - `PRODUCTION.md` (207 lines) - `PRODUCTION_PLAN.md` (292 lines) - `CONTRIBUTING.md` (87 lines) - `SECURITY.md` (7 lines) - `ROADMAP.md` (70 lines) - `DECISIONS.md` (2931 lines — 75 ADRs) - `BENCHMARKS.md` (1743 lines — all benchmark results) ### Additional Content to Extract from Source Code - All 12 examples require docs treatment - `demo_shop/` e2e app needs case study - All 5 cloud deployment guides (`deploy/clouds/*.md`) - Helm chart documentation - CLI reference (9 subcommands) - Fuzz testing documentation - All ADRs from DECISIONS.md --- ## Implementation Roadmap ``` Phase 0: Site Infrastructure [Week 1] — config, nav structure, design system Phase 1: Getting Started [Week 1] — 1 enhance + 1 new page Phase 2: Tutorials [Week 2] — 1 enhance + 10 new pages Phase 3: API Reference [Week 3-4] — 16 new pages (largest section) Phase 4: Advanced Guides [Week 4-5] — 1 enhance + 8 new pages Phase 5: Deployment [Week 5] — 3 enhance + 6 new pages Phase 6: Security [Week 6] — 4 new pages Phase 7: Observability [Week 6] — 4 new pages Phase 8: Reference [Week 7] — 1 enhance + 5 new pages Phase 9: Contributing [Week 7] — 5 new pages Phase 10: Inference [Week 8] — 4 new pages Phase 11: Examples Gallery [Week 8] — 1 new page Phase 12: Technical QA [Week 8-9] — automation, CI, design polish Phase 13: Final Audit [Week 9] — content completeness, link check, Lighthouse ``` Total new pages: **~75** (enhancements to 6 existing pages, ~69 completely new) --- ## Key Design Principles 1. **Every page must answer:** What is it? Why does it matter? How do I use it? Where does it fit in the architecture? 2. **Code examples always runnable** — tested with the actual framework 3. **Performance numbers everywhere** — JustAPI's differentiator is speed; every feature page should show the benchmark 4. **Visual hierarchy** — architecture diagrams (Mermaid), screenshots, comparison tables 5. **Progressive disclosure** — tutorial → how-to → reference → deep-dive 6. **Search-first** — every concept should be findable via Pagefind within 2 clicks 7. **Mobile-friendly** — all diagrams, tables, and code blocks responsive 8. **Accessible** — WCAG 2.1 AA, semantic HTML, proper ARIA labels --- ## Directory Structure (Target) ``` docs_site/ ├── astro.config.mjs ├── package.json ├── tsconfig.json ├── public/ │ ├── favicon.svg │ └── og-image.png ├── src/ │ ├── assets/ │ │ ├── logo.svg │ │ ├── architecture.svg │ │ └── bench-comparison.png │ ├── components/ │ │ ├── BenchTable.astro # Reusable benchmark comparison table │ │ ├── CodeExample.astro # Styled code block with copy button │ │ ├── ArchitectureDiagram.astro # Mermaid diagram component │ │ ├── FeatureCard.astro # Feature highlight card │ │ ├── CompatibilityBadge.astro # FastAPI/Starlette parity badge │ │ └── Callout.astro # Info/warning/tip callout │ ├── content/ │ │ ├── config.ts │ │ └── docs/ │ │ ├── index.mdx │ │ ├── getting-started/ │ │ │ ├── overview.md │ │ │ ├── installation.md │ │ │ ├── first-steps.md │ │ │ ├── cli-scaffolder.md │ │ │ └── migrating-from-fastapi.md │ │ ├── tutorials/ │ │ │ ├── hello-world.md │ │ │ ├── path-query-params.md │ │ │ ├── request-body.md │ │ │ ├── dependency-injection.md │ │ │ ├── middleware.md │ │ │ ├── error-handling.md │ │ │ ├── file-uploads.md │ │ │ ├── websockets-sse.md │ │ │ ├── database-integration.md │ │ │ ├── background-tasks.md │ │ │ └── routing-subrouters.md │ │ ├── api-reference/ │ │ │ ├── index.md │ │ │ ├── justapiapp.md │ │ │ ├── routing.md │ │ │ ├── apirouter.md │ │ │ ├── request.md │ │ │ ├── responses.md │ │ │ ├── dependency-injection.md │ │ │ ├── exceptions.md │ │ │ ├── schema-validation.md │ │ │ ├── websockets.md │ │ │ ├── background-tasks.md │ │ │ ├── scheduler.md │ │ │ ├── session.md │ │ │ ├── plugins.md │ │ │ ├── testing-client.md │ │ │ ├── uploadfile.md │ │ │ └── database.md │ │ ├── advanced/ │ │ │ ├── zero-gil-architecture.md │ │ │ ├── rust-core-deep-dive.md │ │ │ ├── pyo3-ffi-safety.md │ │ │ ├── native-fast-path.md │ │ │ ├── multi-protocol-apis.md │ │ │ ├── agent-system.md │ │ │ ├── streaming-output.md │ │ │ ├── performance-tuning.md │ │ │ └── resilience-patterns.md │ │ ├── deployment/ │ │ │ ├── docker.md │ │ │ ├── kubernetes-helm.md │ │ │ ├── cloudflare-pages.md │ │ │ ├── gke.md │ │ │ ├── eks.md │ │ │ ├── aks.md │ │ │ ├── flyio.md │ │ │ ├── railway.md │ │ │ └── production-checklist.md │ │ ├── security/ │ │ │ ├── policy.md │ │ │ ├── owasp-compliance.md │ │ │ ├── penetration-testing.md │ │ │ └── secure-configuration.md │ │ ├── observability/ │ │ │ ├── metrics-monitoring.md │ │ │ ├── opentelemetry.md │ │ │ ├── structured-logging.md │ │ │ └── health-checks.md │ │ ├── reference/ │ │ │ ├── cli.md │ │ │ ├── configuration.md │ │ │ ├── release-notes.md │ │ │ ├── adr-index.md │ │ │ ├── error-codes.md │ │ │ └── glossary.md │ │ ├── contributing/ │ │ │ ├── development-setup.md │ │ │ ├── coding-standards.md │ │ │ ├── testing-guide.md │ │ │ ├── benchmarking-guide.md │ │ │ └── documentation-guide.md │ │ ├── inference/ │ │ │ ├── overview.md │ │ │ ├── llm-serving-api.md │ │ │ ├── gpu-cuda-setup.md │ │ │ └── scheduling-batching.md │ │ └── examples/ │ │ └── index.md │ └── styles/ │ └── custom.css # Expanded design system └── dist/ # Build output ``` --- ## Execution Priorities ### Required for MVP (v1 docs site launch) 1. Phase 0: Site nav + design system 2. Phase 1: All Getting Started (complete — already have 4/5 pages) 3. Phase 2: Tutorials (most user-facing value) 4. Phase 3: API Reference (most referenced by users) 5. Phase 5.9: Production Checklist (critical for ops audience) 6. Phase 6: Security (trust signal) 7. Phase 8.1: CLI Reference (dev tool UX) 8. Phase 9: Contributing Guide (community growth) ### v2 enhancements 9. Phase 4: Advanced Guides (deep technical audience) 10. Phase 5: Cloud Deployment Guides (multi-cloud) 11. Phase 7: Observability (production operations) 12. Phase 10: Inference (AI/ML audience) 13. Phase 11: Examples Gallery ### Ongoing 14. Phase 8.3: Release Notes + Changelog (per-release updates) 15. Phase 12.2: CI/CD for docs (continuous deployment) 16. Phase 12.4: Quality assurance (link checking, Lighthouse) --- ## Success Metrics | Metric | Target | |---|---| | **Page coverage** | 100% of public API documented | | **Interactive examples** | Every tutorial page has runnable code | | **Search** | Any concept findable within 2 Pagefind queries | | **Lighthouse** | 100/100 Performance, Accessibility, Best Practices, SEO | | **Load time** | <1s to First Contentful Paint | | **Broken links** | 0 (CI-enforced) | | **Mobile** | All pages pass mobile viewport test | | **Accessibility** | WCAG 2.1 AA compliance | | **Docs build time** | <30s in CI | | **Deployment** | Auto-deploy on merge to main (Cloudflare Pages) | --- *Generated by codebase analysis of all docs/*, *docs_site/*, *crates/*, *examples/*, *deploy/*, *benchmarks/*, *tests/*, *helm/*, *fuzz/*, and root *.md files — capturing 100% of the JustAPI framework surface.*