architecture docs

2026-02-01 12:39:21 -03:00
commit dee8bbfb10
8 changed files with 1155 additions and 0 deletions
--- a/docs/architecture/03-job-flow.dot
+++ b/docs/architecture/03-job-flow.dot
@@ -0,0 +1,101 @@
+digraph job_flow {
+    rankdir=TB
+    node [shape=box, style=rounded, fontname="Helvetica"]
+    edge [fontname="Helvetica", fontsize=10]
+
+    // Title
+    labelloc="t"
+    label="MPR - Job Flow"
+    fontsize=16
+    fontname="Helvetica-Bold"
+
+    graph [splines=ortho, nodesep=0.6, ranksep=0.6]
+
+    // States
+    subgraph cluster_states {
+        label="Job States"
+        style=filled
+        fillcolor="#f8f8f8"
+
+        pending [label="PENDING", fillcolor="#ffc107", style="filled,rounded"]
+        processing [label="PROCESSING", fillcolor="#17a2b8", style="filled,rounded", fontcolor=white]
+        completed [label="COMPLETED", fillcolor="#28a745", style="filled,rounded", fontcolor=white]
+        failed [label="FAILED", fillcolor="#dc3545", style="filled,rounded", fontcolor=white]
+        cancelled [label="CANCELLED", fillcolor="#6c757d", style="filled,rounded", fontcolor=white]
+    }
+
+    // Transitions
+    pending -> processing [label="worker picks up"]
+    processing -> completed [label="success"]
+    processing -> failed [label="error"]
+    pending -> cancelled [label="user cancels"]
+    processing -> cancelled [label="user cancels"]
+    failed -> pending [label="retry"]
+
+    // API actions
+    subgraph cluster_api {
+        label="API Actions"
+        style=dashed
+        color=gray
+
+        create_job [label="POST /jobs/", shape=ellipse]
+        cancel_job [label="POST /jobs/{id}/cancel", shape=ellipse]
+        retry_job [label="POST /jobs/{id}/retry", shape=ellipse]
+    }
+
+    create_job -> pending
+    cancel_job -> cancelled [style=dashed]
+    retry_job -> pending [style=dashed]
+
+    // Executor layer
+    subgraph cluster_executor {
+        label="Executor Layer"
+        style=filled
+        fillcolor="#fff8e8"
+
+        executor [label="Executor\n(abstract)", shape=diamond]
+        local [label="LocalExecutor\nCelery + FFmpeg"]
+        lambda_exec [label="LambdaExecutor\nSQS + Lambda"]
+    }
+
+    processing -> executor
+    executor -> local [label="MPR_EXECUTOR=local"]
+    executor -> lambda_exec [label="MPR_EXECUTOR=lambda", style=dashed]
+
+    // FFmpeg operations
+    subgraph cluster_ffmpeg {
+        label="FFmpeg Operations"
+        style=filled
+        fillcolor="#e8f4e8"
+
+        transcode [label="Transcode\n(with preset)"]
+        trim [label="Trim\n(-c:v copy -c:a copy)"]
+    }
+
+    local -> transcode
+    local -> trim
+
+    // gRPC streaming
+    subgraph cluster_grpc {
+        label="gRPC Communication"
+        style=filled
+        fillcolor="#e8e8f8"
+
+        grpc_stream [label="StreamProgress\n(server streaming)", shape=parallelogram]
+        grpc_submit [label="SubmitJob\n(unary)", shape=parallelogram]
+        grpc_cancel [label="CancelJob\n(unary)", shape=parallelogram]
+    }
+
+    // Progress tracking via gRPC
+    progress [label="Progress Updates\n(gRPC → Redis → DB)", shape=note]
+    transcode -> progress [style=dotted]
+    trim -> progress [style=dotted]
+    progress -> grpc_stream [style=dotted, label="stream to client"]
+    grpc_stream -> processing [style=dotted, label="update status"]
+
+    // gRPC job control
+    create_job -> grpc_submit [label="via gRPC"]
+    grpc_submit -> pending [style=dashed]
+    cancel_job -> grpc_cancel [label="via gRPC"]
+    grpc_cancel -> cancelled [style=dashed]
+}