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

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 (<phase>: <description>)
• Branch naming (phase-N/<short-description>)
• 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)

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

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.