architecture docs

2026-02-01 12:39:21 -03:00
commit dee8bbfb10
8 changed files with 1155 additions and 0 deletions
--- a/docs/architecture/01-system-overview.dot
+++ b/docs/architecture/01-system-overview.dot
@@ -0,0 +1,105 @@
+digraph system_overview {
+    rankdir=TB
+    node [shape=box, style=rounded, fontname="Helvetica"]
+    edge [fontname="Helvetica", fontsize=10]
+
+    // Title
+    labelloc="t"
+    label="MPR - System Overview"
+    fontsize=16
+    fontname="Helvetica-Bold"
+
+    // Styling
+    graph [splines=ortho, nodesep=0.8, ranksep=0.8]
+
+    // External
+    subgraph cluster_external {
+        label="External"
+        style=dashed
+        color=gray
+
+        browser [label="Browser\nmpr.local.ar", shape=ellipse]
+    }
+
+    // Nginx reverse proxy
+    subgraph cluster_proxy {
+        label="Reverse Proxy"
+        style=filled
+        fillcolor="#e8f4f8"
+
+        nginx [label="nginx\nport 80"]
+    }
+
+    // Application layer
+    subgraph cluster_apps {
+        label="Application Layer"
+        style=filled
+        fillcolor="#f0f8e8"
+
+        django [label="Django\n/admin\nport 8701"]
+        fastapi [label="FastAPI\n/api\nport 8702"]
+        timeline [label="Timeline UI\n/ui\nport 5173"]
+    }
+
+    // Worker layer
+    subgraph cluster_workers {
+        label="Worker Layer"
+        style=filled
+        fillcolor="#fff8e8"
+
+        grpc_server [label="gRPC Server\nport 50051"]
+        celery [label="Celery Worker\n(local)"]
+        lambda [label="Lambda\n(cloud)", style="dashed,rounded"]
+    }
+
+    // Data layer
+    subgraph cluster_data {
+        label="Data Layer"
+        style=filled
+        fillcolor="#f8e8f0"
+
+        postgres [label="PostgreSQL\nport 5433", shape=cylinder]
+        redis [label="Redis\nport 6380", shape=cylinder]
+        sqs [label="SQS\n(cloud)", shape=cylinder, style=dashed]
+    }
+
+    // Storage
+    subgraph cluster_storage {
+        label="File Storage"
+        style=filled
+        fillcolor="#f0f0f0"
+
+        local_fs [label="Local FS\n/media", shape=folder]
+        s3 [label="S3\n(cloud)", shape=folder, style=dashed]
+    }
+
+    // Connections
+    browser -> nginx
+
+    nginx -> django [label="/admin"]
+    nginx -> fastapi [label="/api"]
+    nginx -> timeline [label="/ui"]
+
+    // Django uses FastAPI for operations (single API gateway)
+    django -> fastapi [label="job operations"]
+    django -> postgres [label="CRUD only"]
+
+    // Timeline UI uses FastAPI
+    timeline -> fastapi [label="REST API"]
+
+    // FastAPI is the single API gateway
+    fastapi -> postgres
+    fastapi -> redis [label="job status"]
+    fastapi -> grpc_server [label="gRPC\nprogress streaming"]
+
+    // Worker layer
+    grpc_server -> celery [label="task dispatch"]
+    celery -> redis [label="queue"]
+    celery -> postgres [label="job updates"]
+    celery -> grpc_server [label="progress\ncallbacks", style=dotted]
+    celery -> local_fs [label="read/write"]
+
+    // Cloud (future)
+    lambda -> sqs [label="queue", style=dashed]
+    lambda -> s3 [label="read/write", style=dashed]
+}