Inside the HeatCredit
infrastructure.
HeatCredit operates on a fully serverless, event-driven cloud architecture engineered for mathematical rigor, ephemeral execution, and zero idle compute waste. A deterministic pipeline translates raw building envelopes and physical weather feeds into auditable resilience decisions.
One system. Clearly connected.
Structured into five discrete architectural swimlanes. Click any service card to inspect its verified runtime specifications, IAM policy attachments, data contracts, and source code anchors.
Client & Ingress
Amplify Edge & API Gateway
Next.js Client (Amplify)
Editorial Web Console & Decision Workspace
Amazon API Gateway
Edge Ingress, CORS & Rate Limiting
Serverless Compute
ARM64 Graviton Lambdas (256MB)
Assessment Lambda
Deterministic 7-Dimension Scoring Engine
Optimization Lambda
0/1 Knapsack Decision Algorithm
Weather Proxy Lambda
Open-Meteo Ingestion & Fallback Router
Warnings Lambda
Official NWS / Alert Integration
Interventions Lambda
Canonical Catalogue Provider
Health Ping Lambda
Liveness & Diagnostic Probe
Persistence
DynamoDB On-Demand Tables
Assessments Table
Persistent Audit Trail for Building Assessments
Recommendations Table
Optimized Package Allocation Records
External Feeds
Open-Meteo, NWS & Fallback
Open-Meteo REST API
Live Meteorological Telemetry Feeds
NOAA / NWS Alert Feeds
Official Heat Advisory & Warning Feeds
Regional Fallback Cache
Offline High-Availability Safeguard
Observability
CloudWatch Logs & Alarm
AWS CloudWatch Logs
Centralized Audit Logging & Execution Tracing
Lambda Error Alarm
Automated Failure Alerting & State Check
Assessment Lambda
Executes the pure mathematical 7-dimension scoring engine. Translates physical envelope attributes (roof assembly, shading, ventilation, hydration, cooling, green cover, exposure) into an auditable resilience score and writes assessment records to DynamoDB.
Bound strictly to least-privilege policies defined in SAM template. No administrative access or unrestricted wildcards.
From physical input to auditable decision.
Every facility evaluation follows an immutable 6-stage execution lifecycle through AWS API Gateway and isolated ARM64 Lambda environments.
Client Intake
Facility administrator enters physical envelope parameters (roof material, shade, ventilation, occupancy, cooling). Client validates numerical bounds locally.
Regional Ingress
Regional REST endpoint receives HTTPS POST. Evaluates rate limiting (100 rps) and validates CORS headers. Dispatches synchronous event to Lambda.
Boundary Validation
Zod-compatible validation verifies required attributes, bounds checks numbers (occupancy 1–100k, hours 1–24), and rejects NaN or malicious payloads.
Deterministic Math
Executes pure mathematical formulation across 7 physical dimensions. No statistical hallucination. Calculates exact score (0–100) and gap priorities.
Persistence & Provenance
Writes immutable assessment record with UUID, calculated tier (Critical to Resilient), timestamp, and 30-day TTL to AssessmentsTable.
Audit Response
Returns HTTP 200 with score breakdown, timestamped provenance hash, and verified baseline attribution back to the decision console.
Designed for clarity. Built for accountability.
Security boundaries are mathematically enforced in code and constrained by AWS IAM least-privilege policies. No broad wildcards, no public database access.
Scoped IAM Least Privilege
Functions do not possess administrative permissions. AssessmentFunction is bound strictly to DynamoDBCrudPolicy on AssessmentsTable only. OptimizationFunction has read-only access to assessments and write access to recommendations.
Input Sanitization & Schema Defense
All ingress payloads pass through physical boundary validation before any computation occurs. Numerical bounds are clamped (occupancy 1–100,000, daily operating hours 1–24, canopy coverage 0–100%). Any NaN, Infinity, or negative numbers are rejected with HTTP 400.
Ephemeral MicroVM Isolation
Lambda invocations execute within isolated Firecracker microVMs on AWS Graviton (ARM64). Execution environments are stateless: no data persists between requests on local storage, and execution logs contain no customer secrets or confidential facility keys.
Production telemetry and deployment pipeline.
Transparent continuous delivery and real-time operations without opaque monitoring dependencies.
Continuous Delivery Workflow
Main repository branch feature/phase-3-building-evidence triggers automatic build webhooks on commit.
Builds apps/web with Turbopack, creates optimized SSR and static prerender bundles, and deploys across CloudFront edge locations.
template.yaml bundles TypeScript Lambdas via esbuild into ARM64 distributions and deploys CloudFormation stack heatcredit-prod.
CloudWatch Observability
All 6 Lambda log groups (/aws/lambda/heatcredit-*-prod) are locked to 7-day retention to prevent AWS cost runaway while maintaining full auditability.
Triggers alarm status if cumulative Lambda errors reach or exceed 5 occurrences within any 5-minute evaluation window (Period: 300s).
Synthetic probe verifies cold-start availability, DynamoDB connectivity, and OpenAPI router integrity.
Ready to inspect the mathematical formulation?
Dive into the pure physical equations governing building envelope scores, or launch the interactive knapsack optimizer to simulate budget allocations.