Skip to content
AnglinAI Docs

Customer AWS Stack - Implementation Plan

Goal

Offer a customer-managed AWS deployment using our CDK stacks and a coordination layer so the service can run inside the customer’s AWS account and we do not handle production document data.

Relationship To Existing Docs

This document is the implementation plan. It complements:

  • docs/admin/customer-aws-deployment.md
  • docs/admin/aws-deploy-next-steps.md

Those documents describe feasibility and current AWS status. This document describes what must be built to productize customer-owned AWS deployments.

Product Promise

For a supported customer AWS deployment:

  • application services run in the customer AWS account
  • customer data remains in customer-owned storage, queues, and databases
  • our coordination layer handles updates, health, license validation, and support hooks without requiring access to document content

Scope

Phase 1 should target one supported topology:

  • customer-owned AWS commercial account
  • single-region deployment
  • our CDK-managed infrastructure
  • our support coordination plane

GovCloud, multi-region HA, and customer-owned auth/payment substitutions can follow later.

Major Workstreams

  1. Deployment packaging and environment model
  2. Coordination layer
  3. Configuration and secrets bootstrap
  4. Tenant/customer isolation model
  5. Operational runbooks and upgrade process

Technical Plan

Phase 1 - Define the Supported Reference Architecture

Freeze a supported architecture before coding product surfaces.

Reference architecture should specify:

  • frontend hosting model
  • API compute model
  • worker model
  • queues
  • object storage
  • database
  • auth
  • observability
  • outbound AI integrations

Output:

  • one architecture diagram
  • one supported service matrix
  • one list of unsupported substitutions

Phase 2 - Customer Environment Bootstrap

Build a repeatable bootstrap path:

  • AWS account prerequisites
  • IAM roles
  • domain and certificate inputs
  • SSM / Secrets Manager structure
  • required external secrets

Artifacts:

  • bootstrap script
  • CDK environment template
  • prerequisites checklist

Phase 3 - Coordination Layer

The customer asked for a coordination layer. Define it explicitly.

Recommended responsibilities:

  • license validation
  • release channel selection
  • health heartbeat
  • support diagnostics metadata
  • signed update manifests
  • optional usage telemetry without document content

Explicit non-responsibilities:

  • document access
  • raw storage browsing
  • direct shell access

This component can be a lightweight service or agent running in the customer environment with outbound-only communication.

Phase 4 - Configuration Externalization

Remove or parameterize any hosted assumptions:

  • hardcoded domains
  • hosted callback URLs
  • default CORS origins
  • hosted storage paths
  • hosted auth assumptions
  • email sender defaults

The deployment must be driven by environment configuration, not code forks.

Phase 5 - Secrets and Key Management

Define where each class of secret lives:

  • app secrets
  • auth secrets
  • storage credentials if any
  • AI provider credentials
  • Stripe or replacement billing secrets if used

Recommended default:

  • AWS Secrets Manager for long-lived secrets
  • SSM Parameter Store for non-secret config

Phase 6 - Deployment Orchestration

Create a CDK deployment product that can:

  • deploy the reference stack
  • run migrations safely
  • build or reference required container images
  • output operator-facing URLs and next steps

Need a clear decision on whether we:

  • deploy our own prebuilt images from ECR or GHCR
  • build images inside the customer account pipeline

For stricter customers, building inside the customer account is preferable.

Phase 7 - Day-2 Operations

Productizing AWS deployment is mostly an operations problem after first install.

We need supported processes for:

  • upgrades
  • rollbacks
  • secret rotation
  • certificate renewal
  • scaling workers
  • storage growth
  • AI provider outages
  • support diagnostics export

Phase 8 - Customer Documentation

Produce operator docs for:

  • installation
  • required IAM permissions
  • networking and egress requirements
  • AI provider setup
  • backup and recovery
  • upgrades
  • support boundaries

Open Product Decisions

  • Does the customer keep Supabase, or do we require a pure AWS stack?
  • Is Cognito required for customer-managed deployments, or is self-hosted auth allowed?
  • Is Stripe required, optional, or excluded from customer-managed deployments?
  • Do we support customer-owned AI keys only, or also our hosted AI accounts from inside their VPC?

These decisions affect scope materially and should be resolved before implementation starts.

To reduce scope, MVP should require:

  • customer-owned S3, SQS, and EC2/ECS
  • customer-provided AI keys
  • our current auth/database path if acceptable
  • outbound-only coordination agent

That gets us a meaningful privacy story without rewriting the whole platform in one pass.

Deliverables

  • CDK reference deployment package
  • bootstrap script and prerequisites checker
  • coordination layer service/agent
  • operator install guide
  • upgrade and rollback runbook

Acceptance Criteria

  • A customer can deploy the supported stack into their AWS account using documented steps.
  • The deployed system can process documents without our hosted storage path.
  • We can observe deployment health without accessing customer document content.
  • Upgrade and rollback paths are documented and tested.

Estimated Effort

  • Architecture and packaging: 4-6 days
  • coordination layer: 5-8 days
  • bootstrap and docs: 3-5 days
  • deployment hardening and QA: 5-8 days
  • Total MVP: 17-27 days