Infra And Deployment

Plan Metadata

• Plan type: plan
• Parent plan: N/A
• Depends on:
• auth-system.md
• memory-upload-flow.md
• aws-cost-alerting.md
• Status: documentation

Status semantics: - draft: Plan is being created or updated and is not final. - approved: Plan is approved but not yet applied in code. - documentation: Code currently exists and matches the plan contract.

Update rule: - When an existing plan is edited, set status to draft until re-approved.

System Intent

• What is being built: Source-of-truth deployment and infrastructure contract covering local runtime, SAM deployment, Terraform deployment, and shared AWS surfaces consumed across feature plans.
• Primary consumer(s): Engineers deploying or operating server/auth/upload/feed/cost-alerting surfaces.
• Boundary (black-box scope only): Deployment order, required inputs, and resulting shared infrastructure surfaces and runtime availability guarantees.

Stage Gate Tracker

• [x] Stage 1 Mermaid approved
• [x] Stage 2 I/O contracts approved
• [x] Stage 3 pseudocode/technical details approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  C[Server Deploy Surface - main/server/template.yaml]
  D[Infra Resource Definitions Surface - main/devops/main.tf]
  Q[Infra Operator Variables Surface - main/devops/terraform.tfvars.example]
  R[Infra Variable Inputs Surface - main/devops/variables.tf]
  Q -->|template used to populate input values| R
  R -->|input values and variable declarations feed main apply| D
  D -->|writes shared runtime parameters consumed by sam template| C
  C -->|exports stack outputs consumed by terraform resources| D

  D -->|uses default vpc subnets route table endpoint plumbing| J[VPC Surface - external aws/vpc]
  D -->|writes shared db and network parameters| K[SSM Surface - external aws/ssm]
  D -->|provisions bastion host and security groups| N[EC2 Surface - external aws/ec2]
  D -->|provisions encache-base-ml repository| O[ECR Surface - external aws/ecr]
  D -->|delegates auth-only infra contract to auth plan| T[Auth Infra Contract Boundary - docs/plans/auth-system.md]
  D -->|provides upload infra dependencies owned by upload contract| U[Memory Upload Contract Boundary - docs/plans/memory-upload-flow.md]
  D -->|routes cost-alerting ownership to related plan contract| V[Cost Alerting Contract Boundary - docs/plans/aws-cost-alerting.md]
  S[Infra Output Surface - main/devops/outputs.tf]
  J -->|network identifiers exposed via terraform outputs| S
  N -->|bastion identifiers exposed via terraform outputs| S

  B[Local Runtime Entrypoint Exists - main/server/scripts/start-local.sh]

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class B,C,D,J,K,N,O,Q,R,S,T,U,V unchanged;

Core infra file map for Stage 1: - Resource definitions: main/devops/main.tf - Variable inputs: main/devops/variables.tf - Output surface: main/devops/outputs.tf - Operator variable template: main/devops/terraform.tfvars.example

Local runtime config files (not diagrammed): - main/server/sam-env.local.example.json - main/server/sam-container-env.local.example.json - main/server/samconfig.toml

Stage 1 discovery notes for cross-plan infra coverage: - Upload-facing infra surfaces are intentionally represented through memory-upload-flow.md instead of duplicating S3/DB-facing interface nodes in this plan. - Auth-only infra contract is maintained in auth-system.md (Auth service infra block) so auth can be extracted/redeployed independently. - aws-cost-alerting.md owns the cost/Discord resource contract; this infra plan only references it as a related plan and does not duplicate those runtime contracts. - memory-feed.md and conversation-feed.md own API contracts, but not route deployment ownership in main/server/template.yaml. - Local deployment assets (main/server/scripts/start-local.sh, main/server/sam-env.local.example.json, main/server/samconfig.toml) currently reference function/parameter names not present in template.yaml; this drift should be tracked in this infra plan.

2. Black-Box Inputs and Outputs

Keep this section at deployment-contract level (inputs/outputs and observable outcomes), not implementation internals.

Global Types

StandardError {
  status?: number
  code?: string
  message: string
}

LocalRuntimeConfigState {
  sam_env_file_present: boolean
  sam_container_env_file_present: boolean
  required_non_placeholder_keys_present: boolean
}

LocalRuntimeBootstrapOutput {
  local_db_ready: boolean
  local_api_ready: boolean
  generated_sam_env_file?: string
}

SharedInfraOwnershipOutput {
  owning_plan: string
  owning_files: string[]
  ownership_status: "owned" | "gap"
  notes?: string
}

Flow: main/server/scripts/start-local.sh.main, N/A

Type Definitions

LocalRuntimeBootstrapInput {
  entrypoint_path: "main/server/scripts/start-local.sh"
  required_files: [
    "main/server/sam-env.local.json",
    "main/server/sam-container-env.local.json"
  ]
  config_state: LocalRuntimeConfigState
}

LocalRuntimeBootstrapFlowOutput = LocalRuntimeBootstrapOutput

Paths

Flow: docs/plans/infra-and-deployment.md.resolveSharedInfraOwnership, N/A

Type Definitions

SharedInfraOwnershipInput {
  surface: string
}

SharedInfraOwnershipFlowOutput = SharedInfraOwnershipOutput

Paths

3. Pseudocode / Technical Details for Critical Flows (Optional)

• Flow name:: deployment-file-purpose-map

  main/server/template.yaml:
    defines deployable server stack surfaces and publishes auth trigger ARN outputs
  
  main/devops/main.tf:
    defines shared infra resources and shared /encache/* SSM parameter wiring
  
  main/devops/variables.tf:
    defines required and optional input variables consumed by main.tf
  
  main/devops/outputs.tf:
    defines operator-facing outputs produced from main.tf-managed resources
  
  main/devops/terraform.tfvars.example:
    documents safe operator input template for main.tf variables
  
  main/server/scripts/start-local.sh:
    validates local env files, starts local db, builds lambdas, and starts local api
  

• Flow name:: shared-infra-ownership-routing

  if infra surface is auth-focused:
    route ownership to docs/plans/auth-system.md auth service infra block
  if infra surface is upload-facing interface behavior:
    route ownership to docs/plans/memory-upload-flow.md
  if infra surface is discord cost alerting:
    route ownership to docs/plans/aws-cost-alerting.md
  if no owner exists:
    mark ownership_status=gap and block completion until assigned
  

• Implementation notes:
• This section clarifies file purpose and ownership routing only.
• Behavioral contracts remain in Section 2 and linked owning plans.

4. Handoff to Related Plan Reconciliation

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.