update docs

2026-05-11 20:13:11 -03:00
commit 2ffabb672e
40 changed files with 5869 additions and 0 deletions
--- a/docs/graphs/system_overview.dot
+++ b/docs/graphs/system_overview.dot
@@ -0,0 +1,70 @@
+digraph system_overview {
+    rankdir=LR
+    bgcolor="#0a0e17"
+    fontname="Helvetica"
+    node [fontname="Helvetica" fontsize=11 style=filled color="#1e2a4a" fontcolor="#e8eaf0"]
+    edge [fontname="Helvetica" fontsize=9 fontcolor="#8892a8" color="#4a5568"]
+
+    label="Sample app — Lambda + MinIO sandbox"
+    labelloc=t
+    fontsize=16
+    fontcolor="#0066ff"
+
+    subgraph cluster_caller {
+        label="Caller"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        invoke [label="invoke.py\n(local) /\nAPI Gateway,\nS3 event,\nStep Functions\n(real AWS)" fillcolor="#243056" shape=box]
+    }
+
+    subgraph cluster_lambda {
+        label="Lambda execution environment"
+        style=dashed
+        color="#0066ff"
+        fontcolor="#0066ff"
+
+        handler [label="handler(event, context)\nlambda_function.py" fillcolor="#1a1a3a" shape=box]
+
+        subgraph cluster_async {
+            label="asyncio.Queue producer / consumer"
+            style=dotted
+            color="#0066ff"
+            fontcolor="#8892a8"
+
+            producer [label="producer\nlist_objects_v2 (paginator)\nfilter *.pdf" fillcolor="#0d1a33" shape=box]
+            queue [label="asyncio.Queue\nmaxsize=2000\n(backpressure)" fillcolor="#121829" shape=cylinder]
+            consumer [label="consumer\ngenerate_presigned_url\nappend JSONL" fillcolor="#0d1a33" shape=box]
+        }
+
+        tmp [label="/tmp/<uuid>.jsonl\nstreamed manifest\n(ephemeral, 512 MB default)" fillcolor="#121829" shape=cylinder fontcolor="#ffc107"]
+    }
+
+    subgraph cluster_storage {
+        label="Object storage"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        minio [label="MinIO (local)\nor real S3" fillcolor="#1a3a1a" shape=cylinder fontcolor="#00c853"]
+        bucket [label="my-company-reports-bucket\n2026/04/*.pdf\nmanifests/<uuid>.jsonl" fillcolor="#121829" shape=folder]
+    }
+
+    response [label="response\n{count, manifest_key,\nmanifest_url}\n(< 1 KB; sidesteps 6 MB cap)" fillcolor="#243056" shape=note fontcolor="#00c853"]
+
+    invoke -> handler [label="event"]
+    handler -> producer [label="spawn task"]
+    handler -> consumer [label="spawn task"]
+
+    producer -> minio [label="LIST"]
+    minio -> producer [label="page (1000 keys)" style=dashed]
+    producer -> queue [label="key" color="#0066ff"]
+    queue -> consumer [label="key"]
+    consumer -> minio [label="presign\n(local HMAC)" style=dotted]
+    consumer -> tmp [label="JSONL line"]
+
+    tmp -> minio [label="put_object\nmanifests/<uuid>.jsonl"]
+    handler -> response [label="return"]
+    minio -> bucket [style=invis]
+}