Skip to content

requirement.md

Latest commit

 

History

History
148 lines (104 loc) · 4.51 KB

requirement.md

File metadata and controls

148 lines (104 loc) · 4.51 KB
Raw

REQUIREMENTS.md

0) Project Name & Goal

Project: Iron Systems – From Locks to Actors
Goal: Build a production-flavored blueprint for high-concurrency distributed systems that demonstrates the Four Pillars of Performance:

  1. Parallel Reads (lock-free, cache-first)
  2. Serialized Writes (single writer per key/partition)
  3. Read/Write Separation (write path mutates truth; read path serves snapshots)
  4. Asynchronous State (event-driven consistency, replayable)

Deliver two implementations under one repo:

  • Python/FastAPI + aiokafka + redis + asyncpg
  • Go (Gin/Fiber) + Sarama (Kafka) + go-redis + pgx

The two versions should mirror the same architecture and behavior.

1) Success Criteria (Acceptance)

Functional

  • POST /reserve enqueues a reservation command keyed by slot_id.
  • GET /slots/{id} returns remaining capacity from cache (Redis); supports Stale-While-Revalidate (SWR).
  • Worker consumes messages per partition, processes actor-style single writer, persists to PostgreSQL with idempotency, and refreshes cache.
  • Unique constraints prevent duplicate reservations: a user may reserve a timeslot only once; a timeslot has a configurable capacity.

Performance (local dev box + Docker Compose)

  • Write path (enqueue → process → persist → cache refresh):
    • ≥ 5,000 RPS sustained; P99 < 250ms end-to-end under normal conditions.
  • Read path (cache hit):
    • ≥ 50,000 RPS; P95 < 20ms.
  • Read path (cache miss, SWR):
    • ≥ 10,000 RPS; P95 < 60ms.
  • Stability: 60-minute run without message loss; Kafka lag bounded and recovers after spikes.

Observability

  • /metrics (Prometheus) exposes RED metrics (Rate/Errors/Duration) per service, plus:
    • Kafka consume/produce rates & lag
    • Worker batch size, flush latency
    • DB TPS (optional), Redis hit ratio (optional)
  • Tracing (OpenTelemetry) spans across API → producer → worker → DB (best-effort; if time is tight, keep hooks ready).

Reliability

  • Idempotency via request key (Idempotency-Key header or (user_id, slot_id) unique pair) + DB constraints.
  • Retry with backoff for transient Kafka/Redis/DB errors.
  • DLQ: if a message fails N times, route to dead-letter topic with reason; provide a manual replay script.
  • Graceful shutdown: drain in-flight requests/records.

Documentation & DevEx

  • One-command startup: make up (Docker Compose).
  • Swagger/OpenAPI available for API.
  • README includes architecture diagram, quickstart, perf results screenshot, and design tradeoffs.
  • Minimal Locust (or k6) scenario for write & read loads with a report.

2) Architecture Overview

(High-level ASCII diagram omitted here for brevity — see diagrams/architecture.png in final repo.)

3) Data Model & Keys

(See detailed schema above.)

4) APIs

POST /reserve, GET /slots/{id}, etc.

5) Repository Layout

(Full folder tree with python/go versions.)

6) Implementation Notes

Describes Actor, Producer, Consumer logic, Redis caching, SWR behavior, etc.

7) Observability

Prometheus, Grafana, OpenTelemetry setup.

8) Dev & Ops

Docker Compose, Makefile commands, etc.

9) Testing & Benchmark

Unit, Integration, Locust/k6 tests.

10) Stretch Goals

DLQ, Replay, Outbox, WS Push, Sharding.

11) Coding Standards & PR Checklist

Lint, CI/CD, metrics, OpenAPI, etc.

12) Example ENV Vars

KAFKA=localhost:9092
REDIS=redis://localhost:6379
PG=postgres://dev:dev@localhost:5432/app
GROUP=iron-worker
TOPIC=reservations

13) Milestones (Execution Order)

Bootstrap → Python → Go → Metrics → Load Test → README polish.

14) Documentation (Blogs)

01-four-pillars.md
02-from-locks-to-actors.md
03-linux-vs-zephyr-devicetree.md
04-1b-interactions-architecture.md

15) Branding (tone)

We don’t fight locks — we redesign contention.
Parallel reads, serialized writes, read/write separation, async state.
Locks are a human reflex to inconsistency; asynchrony is computation’s natural posture. — Harrison

Deliverables:

  • Working Python & Go services under python/ and go/ with identical behavior.
  • Docker Compose one-click run.
  • Metrics exposed; basic dashboard JSON (optional).
  • Benchmarks + README screenshots.
  • Blogs & diagrams included.

If a tradeoff is needed due to time, prioritize correctness by design, observability, and benchmarks over extra features.