ARCHITECTURE.md

System Architecture & Lifecycle Pipeline

1. High-Level Architectural Flow

[React Frontend] --(Presigned S3 URL)--> [AWS S3 Bucket]
       |                                       ^
 (Upload Meta API)                             |
       v                                       |
[FastAPI Router] --(Dispatches Job)--> [Redis Broker]
       |                                       |
 (Returns Task ID)                             v
       v                            [Celery Parser Worker]
[Client Polling] <--(Fetches Result)-- [PostgreSQL DB Engine]

2. Core Execution Steps

1. Ingestion Layer: The client requests a secure upload route. FastAPI issues an S3 Presigned URL. The frontend pushes raw code directly to S3.
2. Background Handshake: FastAPI registers the request parameters and dispatches an asynchronous parsing payload to Redis, instantly returning a unique task_id to the UI thread.
3. AST Parser Execution: A specialized Celery worker pulls the task, fetches the code artifact from S3, and compiles it down via Python's internal ast compiler engine into functional JSON nodes.
4. Persistence & Presentation: The resulting node/edge graph configuration is stored permanently within PostgreSQL. The frontend continuously loops or opens a connection to fetch the ready architecture payload and passes it directly to React Flow.