swadhin / justapi public

p1a: enhance Overview page — audience, architecture diagram, benchmarks, feature comparison

swadhinbiswas committed 3 months ago
89769d4
1 parent 88b069e
commit 89769d4
1 file changed
+80 -0
Showing 1 changed file+80-0
docs_site/src/content/docs/getting-started/overview.md
▼docs_site/src/content/docs/getting-started/overview.md
+80-0
@@ -7,9 +7,89 @@ description: Learn why JustAPI is built on Rust and how it delivers FastAPI comp
7
7
8
8
It is engineered as a **drop-in replacement for FastAPI** — preserving your favorite Python decorator syntax, Pydantic schemas, dependency injection, and automatic OpenAPI documentation — while offloading networking, TLS, routing, request validation, and response serialization to Rust.
9
9
10
+## Who Is This For?
11
+
12
+| Audience | Why JustAPI |
13
+|---|---|
14
+| **FastAPI users** | Drop-in replacement. Change one import. Get 20x throughput. |
15
+| **Performance engineers** | 700k+ RPS in a single process. Sub-millisecond p99 latency. |
16
+| **AI/ML teams** | Native MCP tools, streaming validated output, agent session state. |
17
+| **Platform teams** | Built-in OTel, Prometheus metrics, health checks, circuit breakers. |
18
+| **Startups** | One framework for REST, GraphQL, gRPC, JSON-RPC. Ship faster. |
19
+
10
20
## Core Pillars
11
21
12
22
1. **Rust-First Architecture:** The core network stack (Tokio, Hyper, Rustls, Matchit, Serde-JSON, SQLx) is written entirely in Rust.
13
23
2. **FastAPI Parity:** `@app.get()`, `@app.post()`, `APIRouter`, `Depends()`, `HTTPException`, `Header`, `Query`, `Path`.
14
24
3. **Zero-GIL Execution:** Rust releases the Python GIL during all I/O and validation, enabling true parallel execution across multi-core systems.
15
25
4. **Batteries-Included Tooling:** Native database pool, WebSockets, SSE, GraphQL, gRPC, JSON-RPC, OpenTelemetry tracing, and built-in project scaffolding CLI.
26
+
27
+## Architecture Overview
28
+
29
+```
30
+[ Client Connection ]
31
+ │
32
+ ▼
33
+┌───────────────────────────────────────────────┐
34
+│ RUST RUNTIME (justapi-core) │
35
+│ • Socket I/O (tokio) & TLS (rustls) │ 🟢 GIL RELEASED
36
+│ • HTTP/1.1 & HTTP/2 Parsing (hyper) │
37
+│ • Radix Trie Routing (matchit) │
38
+│ • Middleware Chain (auth, CORS, rate-limit) │
39
+│ • JSON Schema Validation (jsonschema-rs) │
40
+│ • Database Queries (sqlx) │
41
+│ • Response Serialization (serde_json) │
42
+└──────────────────────┬────────────────────────┘
43
+ │
44
+ Invoked only for Python application logic:
45
+ ▼
46
+┌───────────────────────────────────────────────┐
47
+│ PYTHON LAYER (justapi-py) │
48
+│ • Business logic / route handlers │ 🟡 PyO3 GIL Thread
49
+│ • Decorator-based API (JustAPIApp) │
50
+│ • Dependency injection (Depends) │
51
+│ • Pydantic / Schema validation bridge │
52
+└───────────────────────────────────────────────┘
53
+```
54
+
55
+## Performance Comparison
56
+
57
+Measured on Intel Core i5-13600K, 31 GiB DDR5. Single process, no multi-worker fan-out.
58
+
59
+| Framework | Requests/sec | p50 Latency | p99 Latency |
60
+|---|---|---|---|
61
+| **JustAPI** | **701,234** | **0.07 ms** | **0.19 ms** |
62
+| Granian | 69,195 | 0.72 ms | 3.87 ms |
63
+| FastAPI + Uvicorn | 36,189 | 1.72 ms | 24.63 ms |
64
+
65
+JustAPI delivers **~20x the throughput** of FastAPI+Uvicorn on the same hardware.
66
+
67
+## Feature Comparison
68
+
69
+| Feature | FastAPI | JustAPI | Notes |
70
+|---|---|---|---|
71
+| Rust-native core | ✗ | ✓ | Tokio + Hyper + matchit |
72
+| Zero-GIL execution | ✗ | ✓ | `py.allow_threads` on all I/O |
73
+| Native DB pool | ✗ | ✓ | sqlx (Postgres, MySQL, SQLite) |
74
+| GraphQL | ✗ (Torture) | ✓ | `app.graphql()` one-liner |
75
+| gRPC | ✗ | ✓ | tonic + prost |
76
+| JSON-RPC 2.0 | ✗ | ✓ | Built-in handler |
77
+| MCP Agent Tools | ✗ | ✓ | `@app.tool` native registration |
78
+| Streaming validation | ✗ | ✓ | `@app.stream_json` with Rust validation |
79
+| Circuit breakers | ✗ | ✓ | Built-in resilience |
80
+| Request coalescing | ✗ | ✓ | Dedup concurrent identical requests |
81
+| OpenTelemetry | ✗ | ✓ | Built-in OTLP exporter |
82
+| Free-threaded Python | ✗ | ✓ | Python 3.13t/3.14t support |
83
+| Multi-arch wheels | ✗ | ✓ | Linux, macOS, Windows, ARM64 |
84
+
85
+## System Requirements
86
+
87
+- **Python:** 3.11, 3.12, 3.13, or 3.14 (including 3.13t/3.14t free-threaded builds)
88
+- **Rust:** 1.85+ (only required when building from source)
89
+- **OS:** Linux (x86_64, ARM64), macOS (x86_64, ARM64), Windows (x64)
90
+
91
+## Next Steps
92
+
93
+- [Installation Guide](/getting-started/installation/) — Install JustAPI in under a minute
94
+- [First Steps](/getting-started/first-steps/) — Build your first API endpoint
95
+- [Migrating from FastAPI](/getting-started/migrating-from-fastapi/) — Switch your existing project
16
96