System Architecture

Reference implementation of a Retrieval-Augmented Generation system overview:

• it embeds a question
• retrieves the most similar chunks from a vector store
• asks an LLM to answer using only those chunks, with citations

System Context Diagram

Expand to explore. This C4 diagram is rendered from LikeC4 DSL source on GitHub with the LikeC4 plugin.

Feature Stack

Component	Technology	Role
Web UI	React + Vite on S3 + CloudFront	Ask a question; show the answer and source chunks
RAG API	FastAPI on Lambda (Mangum), API Gateway HTTP API	Embed query, retrieve, synthesize answer
Database + Vector store	Aurora Serverless v2 + pgvector (RDS Data API)	Store resource chunks and their embeddings
Ingestion	Python (Bedrock Titan)	Load corpus, chunk, embed, upsert
Models	AWS Bedrock (Titan embeddings, Claude)	Embeddings and generation
Knowledge Corpus	neural-bridge/rag-dataset-12000 (Apache-2.0)	Source knowledge outside the LLM’s training, that the pipeline provides

Why these choices

The system optimizes for near-zero idle cost. Aurora Serverless lets the vector store go idle, and Bedrock is pay-per-token with no idle charge. See the cost model, infrastructure, and the Decisions (ADRs) section in the sidebar for the full rationale.

Containers

Expand to see a more detailed view of the system internals:

Query sequence

Expand and START for a live walkthrough of a single query through the system:

One-time knowledge ingestion

Expand to see corpus ingestion, which runs as a local script during development or as a one-off Lambda invocation in AWS:

---

Data-flow paths

Query path

Shown as a mermaid sequence diagram as it shows Authorizer interception and two-Bedrock-hop order more clearly than C4.

CloudFront serves both the SPA and the API on one hostname: /query and /healthz route to the API Gateway origin, everything else to S3. Browser TLS terminates at the CloudFront edge for both; CloudFront opens a new HTTPS connection (TLS 1.2 or later) to API Gateway. Lambda-to-service calls use HTTPS with SigV4 request signing. The API Gateway-to-Lambda invocation is AWS-managed and does not pass through a user-controlled network path.

The RDS Data API hop: Lambda sends an HTTPS ExecuteStatement request to rds-data.us-east-1.amazonaws.com. AWS routes that call to the Aurora cluster through its own service plane. The call does not originate from inside the VPC, and the Aurora security group’s TCP inbound rules are not involved. Authorization is IAM (rds-data:ExecuteStatement on the cluster ARN), enforced by AWS before the call reaches the cluster.

Ingestion path

LikeC4 dynamic view could express this. Using mermaid sequenceDiagram for the same reason as the query path: the local-vs-Lambda conditional and the external Hugging Face hop are cleaner in a sequence diagram than in a LikeC4 dynamic view.

Ingestion runs outside the VPC whether executed locally or as a Lambda invocation. CI runners are GitHub-hosted and reach AWS via an OIDC-federated IAM role; they never enter the VPC. See RAG011 for the data-access contract difference between operator tooling and the application Lambda path.

Observability path

Expand to see observability traffic from each Lambda:

All observability traffic leaves Lambda directly to public AWS service endpoints. No VPC-side flow logs and no network tap are provisioned. The absence of VPC flow logs follows from RAG010: no ENIs emit traffic inside the VPC for flow logs to capture.