Architecture#

POC Factory separates the browser interface, generation backend, external inference, and persistent application state. The backend runs NVIDIA NeMo Agent Toolkit workflows and the Cursor implementation harness; nginx serves the UI and proxies API and streaming traffic.

Components#

The diagram shows the main application, inference, and state connections. Optional integrations are described below.

flowchart TB browser["Browser"] --> frontend["Frontend · React + nginx"] frontend -->|"HTTP API + streamed progress"| backend["Backend · FastAPI + NeMo Agent Toolkit<br/>Cursor CLI implementation harness"] backend --> state["Durable state<br/>PostgreSQL · packages · job store"] backend --> provider["External inference provider<br/>Chat + embedding models"]

Component	Responsibility	Boundary
`poc-factory-frontend`	Browser UI, API reverse proxy, and Server-Sent Events	Public entry point; container port 8080
`poc-factory-mcp`	Generation APIs, workflow execution, validation, packaging, and Cursor CLI	Container port 8000; external inference and optional capability credentials
`github-mcp-proxy-nat-agentic-poc`	Adapts the TypeScript GitHub MCP server’s stdio transport to internal SSE	Port 8080 in Compose or 8081 in Helm; optional read-only GitHub token
PostgreSQL	Users, POC records, and encrypted saved settings	Private database connection; retained database volume or managed service
Mounted application storage	Generated archives, NAT job store, and optional fine-tuning artifacts and datasets	Back up with the database and stable encryption key
Phoenix	Optional OpenTelemetry tracing	Separate dependency; included by the `full` Compose profile

Data Flow#

A generation request moves through nine stages. Human-in-the-Loop mode can pause the PRD, blueprint, and architecture stages for review.

Requirements: Interpret the request and constraints.
PRD: Produce a product requirements document.
Blueprint: Search and rank reference blueprints when useful; select with optional review.
Architecture: Describe components and interfaces.
Code: In default auto mode, author a capability contract, compile the scaffold, and use Cursor for bounded implementation edits.
Tests: Produce contract-derived or generator-specific tests.
Validation: Run the configured static, test, deployment, and runtime gates; retain explicit skips and failures.
Documentation: Package instructions and design artifacts for the generated POC.
Packaging: Save the result and expose a downloadable archive on Dashboard.

The deployment policy controls which validation gates can run. Docker Compose supplies a host Docker socket for generated-container build and runtime checks. The Helm production example disables those Docker-dependent checks, so a successful in-cluster generation does not prove that the generated container builds or runs.

Deployment Topologies#

Both deployment paths use the same three POC Factory release images. PostgreSQL and optional Phoenix remain separate dependencies.

Topology	Best fit	State and validation	Guide
Docker Compose	Private evaluation or a trusted single host	Named volumes and host directories; Docker-dependent candidate validation through the host socket	Docker installation
Kubernetes and Helm	Managed shared service with HTTPS, identity, and storage	PostgreSQL and PVCs; production example disables Docker-dependent validation	Kubernetes installation

The production chart keeps one backend replica. Active progress and some workflow state remain process-local, and the example uses storage that can require a single writer. Multiple frontend replicas do not remove those backend coordination requirements.

Service Interactions#

Users enter through the frontend, which preserves streaming responses for long-running jobs. Use that browser-facing host consistently for API traffic and OAuth callbacks in a shared deployment.

The backend makes outbound calls to its selected model provider and optional integrations. The internal GitHub MCP proxy is not a public user API. Generated packages are retained on mounted storage and associated with database records; saved provider and optional API credentials are encrypted with the deployment’s stable ENCRYPTION_KEY.

External Integration Points#

Configure only the integrations required for your selected workflow.

Integration	Requirement
Inference provider	OpenAI-compatible `/chat/completions` for four chat roles and `/embeddings` for blueprint semantic matching
Cursor	A valid Cursor credential for `auto` or `cursor` generation; administrator keys also require `MODEL_CURSOR`, such as `auto`
GitHub	Optional read-only token for authenticated repository discovery; operations that write require separate authorized permissions
NeMo Microservices	Separate endpoints and credentials for remote model customization workflows
Identity provider	Shared deployments enable application authentication; OAuth requires the configured callback and provider settings
Docker daemon	Required for generated-container build and runtime gates; Compose mounts the host socket