SparkPilot deployment

Control plane, customer account, persistent state and external services.

Runtime flow

The browser enters through HTTPS at the Application Load Balancer. Auth0 sign-in establishes the application session.
Next.js proxies authenticated requests to the private FastAPI address. The API checks identity and resource permissions.
For environment setup and run submission, the API commits the work and outbox record, then publishes its identifier to the appropriate SQS queue.
The worker receives work, loads saved state and advances provisioning or workload submission. Each queue has its own dead-letter queue.
API and worker processes share durable PostgreSQL records. The worker's reconciler saves the AWS job's observed state.
SparkPilot assumes the customer's delegation or provisioning role. EMR workloads use their separate execution identity for scripts, data and logs.
The agent thread calls the external model API over HTTPS. Python controls tool execution and action approval.

Deployment assumptions and verification gaps

Existing control-plane VPC, subnet IDs, routes, certificate and deployment roles are supplied inputs. Their live ownership and settings require an AWS inventory.
Endpoint creation, audit settings, service counts and recovery settings depend on configuration. Terraform check blocks emit warnings; they do not prevent an apply.
Customer access policies differ by provisioning profile. The full-BYOC execution policy contains broad S3, logging and image-read permissions; a universal least-privilege claim would be inaccurate.
WAF, an AWS Config recorder, AWS Budgets and a separate AWS Backup plan are not defined in the inspected modules. They may be managed elsewhere.
Alarm delivery, backup restoration, failure recovery, current availability-zone placement and customer data isolation need runtime evidence. These maps do not establish AWS Well-Architected compliance.

Configuration, source evidence and AWS references

Source snapshot 0851cee, inspected October 16, 2026. The maps show the public HTTPS profile and agent-enabled worker configuration. They are source-reviewed diagrams; active DNS/CDN routing, replica counts, availability-zone placement and egress settings require a current deployment inventory.

infra/terraform/control-plane/main.tf: VPC inputs and API DNS 197–202; worker command 423–425; queues 669–706; network controls 749–982; load balancer 984–1125; task roles and services 1138–1677.
infra/cloudformation/customer-bootstrap-byoc-lite.yaml and customer-bootstrap-full-byoc.yaml: customer role creation and trust. infra/terraform/full-byoc/: customer environment infrastructure.
infra/terraform/control-plane/operations.tf, security_monitoring.tf, audit_logging.tf and terraform_state_backend.tf: alarms, security findings, audit storage and customer provisioning state.
infra/cloudformation/customer-cost-reconciliation.yaml: the separate billing-data role. src/sparkpilot/services/finops.py: allocation and reconciliation limits.
.github/workflows/ci-cd.yml: application release. scripts/terraform/deploy_control_plane.sh: deployment sequencing. .github/workflows/public-site.yml: static-site publication.
infra/terraform/control-plane/cfn_templates.tf: public, read-only bootstrap-template publication. infra/terraform/full-byoc/network/, eks/, emr/ and k8s-runtime/: customer networking, cluster registration and workload identity.
src/sparkpilot/services/control_tower.py: external model requests and local tool dispatch. ui/app/auth/, ui/app/api/auth/session/ and API identity code: application sign-in.

Reviewed against the AWS Well-Architected Framework and official reference diagrams, accessed October 16, 2026. Official AWS icons from the July 31, 2026 package. Visual references: AWS Architecture Icons, ECS inbound networking, cross-account SaaS access and numbered reference-diagram example.