diff --git a/README.md b/README.md
index df0b257..8411987 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,66 @@
# Underflow
-Underflow is a full-stack AWS cost monitoring project built to explore production-style SaaS concerns across backend APIs, frontend workflows, cloud integrations, background jobs, and infrastructure-as-code.
-
-> Warning
-> This repository is still in active development. Core flows are implemented and tested, but some integrations and deployment steps still require manual cloud setup, real credentials, and additional hardening before this should be treated as production-ready.
-
-## Why This Project Is Worth Looking At
-
-Underflow is intentionally broader than a CRUD demo. It brings together:
+[](https://underflow.md-dev970.com)
+
+
+
+
+
+
+
+
+Live app: [underflow.md-dev970.com](https://underflow.md-dev970.com)
+Technical walkthrough: [Architecture Overview](./docs/architecture.md)
+
+Underflow is a live full-stack application for teams that need better visibility into AWS spend across multiple accounts and workspaces. It helps users connect AWS accounts through cross-account roles, sync cost data into a reporting layer, and track spend through dashboards, alerts, and notifications before costs drift too far.
+
+## Problem
+
+AWS cost tooling is powerful, but day-to-day cost visibility can still feel fragmented when a team is working across multiple environments, accounts, and owners. Underflow is built to reduce that friction by giving teams a focused place to:
+
+- organize cloud spend by workspace
+- connect multiple AWS accounts safely through AssumeRole
+- review synced cost data without querying AWS live on every page load
+- create alerts and notification flows around budget drift
+
+## What Underflow Does
+
+- centralizes workspace-based AWS cost monitoring
+- stores connected-account metadata for secure cross-account access
+- syncs and persists cost data for reporting and historical analysis
+- exposes cost summaries, service breakdowns, timeseries views, and sync history
+- supports alert creation, alert evaluation, and notification delivery
+- includes session-based authentication, profile/session management, and password reset flows
+
+## Core Capabilities
+
+- Multi-workspace model for separating teams, environments, or clients
+- AWS account onboarding through a standardized `AssumeRole` flow
+- Persisted reporting model backed by PostgreSQL rather than live Cost Explorer requests on every view
+- Budget alerts and notification workflows backed by worker processes
+- SES-backed auth and alert email delivery
+- Terraform-managed infrastructure for DNS, SES, CI/CD bootstrap, ECS, RDS, S3, and CloudFront
+
+## How It Works
+
+```mermaid
+flowchart LR
+ User["Browser User"] --> Web["React Web App"]
+ Web --> API["Express API"]
+ API --> DB["PostgreSQL"]
+ API --> AWS["AWS Services
STS / Cost Explorer / SES"]
+ Worker["Background Worker"] --> DB
+ Worker --> AWS
+ API --> Customer["Customer AWS Accounts
AssumeRole"]
+```
-- Full-stack TypeScript across an Express API and React frontend
-- Browser/mobile authentication flows with session invalidation and CSRF protection
-- AWS-oriented backend capabilities such as AssumeRole metadata, cost sync orchestration, and SES groundwork
-- Background jobs for sync and alert evaluation
-- Billing-oriented flows and notification infrastructure
-- Terraform-based infrastructure setup for SES and DNS delegation
-- Terraform and GitHub Actions scaffolding for a first ECS/CloudFront production deployment
+Underflow separates the customer-facing frontend, the API, and the background worker so cost syncs, alert evaluation, and notification delivery can run independently from the UI. The backend assumes customer roles only when needed, while synced reporting data stays in PostgreSQL for fast dashboard queries.
-## What Underflow Does Today
+## Why This Project Is Credible
-- Auth for browser and mobile-style clients
-- Workspace-scoped cost monitoring flows
-- AWS account onboarding via AssumeRole metadata
-- Manual and scheduled cost sync foundations
-- Cost summaries, service breakdowns, and timeseries reporting
-- Budget alert creation and notification feed surfaces
-- SES/domain infrastructure bootstrap via Terraform
+- it spans product UI, backend services, background jobs, cloud integrations, and infrastructure
+- it uses real production concerns such as session invalidation, CSRF protection, ECS deployment, SES email, CI/CD, and Terraform-managed AWS resources
+- it is deployed live, not just developed locally
## Tech Stack
@@ -50,45 +85,30 @@ Underflow is intentionally broader than a CRUD demo. It brings together:
### Infrastructure
- Terraform
+- ECS Fargate
+- Amazon RDS for PostgreSQL
+- Amazon S3
+- CloudFront
- Route 53
- Amazon SES
+- GitHub Actions
-## Architecture At A Glance
-
-- `apps/api`
- - Express API, auth/session flows, AWS integrations, background workers, DB migrations, and tests
-- `apps/web`
- - React application for auth, onboarding, workspace management, AWS connection, costs, alerts, and settings
-- `infra/terraform`
- - Shared infrastructure code, currently focused on SES domain setup and Route 53 delegation for a project subdomain
-- `docs`
- - Additional technical documentation and development notes
-
-For a deeper walkthrough, see [docs/architecture.md](./docs/architecture.md).
-
-## Repository Status
-
-This repository is best described as a development-stage, production-style showcase project.
+## Deployment
-### Stable enough to demonstrate
+Underflow is deployed as:
-- Local API and frontend development workflows
-- API migrations
-- Automated API and frontend tests
-- Auth flows
-- Workspace, AWS account, cost-monitoring, and alert management UI
-- SES subdomain infrastructure scaffolding
+- a React frontend served from S3 through CloudFront
+- an Express API running on ECS Fargate
+- a background worker service for sync and alert execution
+- a PostgreSQL database on Amazon RDS
+- AWS-managed DNS, certificates, and email infrastructure
-### Still in progress or requiring manual setup
+For the deployment topology and operational setup, see:
-- Real AWS AssumeRole and Cost Explorer validation against live accounts
-- End-to-end SES production sending approval and live email delivery verification
-- Production deployment topology and operations
-- Final billing/provider hardening
-
-See [docs/status-and-limitations.md](./docs/status-and-limitations.md) for a more concrete maturity summary.
+- [docs/production-deployment.md](./docs/production-deployment.md)
+- [docs/production-operations.md](./docs/production-operations.md)
-## Quickstart
+## Local Development
### Before first run
@@ -162,31 +182,24 @@ npm run build
npm test
```
-## Infrastructure And Email Notes
+## Operational Notes
-- SES/DNS infrastructure now lives under [`infra/terraform`](./infra/terraform)
-- The current recommended pattern is a delegated subdomain such as `underflow.example.com`
-- Terraform can manage:
+- SES and DNS infrastructure lives under [`infra/terraform`](./infra/terraform)
+- the current production pattern uses:
+ - `underflow.` for the web frontend
+ - `api.underflow.` for the API
+- Terraform can provision:
- Route 53 hosted zone, SES identity, DKIM, MAIL FROM, and DMARC records
- bootstrap CI/CD infrastructure such as Terraform remote state and GitHub OIDC
- - production ECS, RDS, S3, and CloudFront deployment topology
-- Parent-domain delegation and SES production-access approval still require manual AWS/DNS steps
+ - production ECS, RDS, S3, CloudFront, and ALB deployment topology
-See:
+Additional references:
-- [docs/local-development.md](./docs/local-development.md)
-- [docs/production-operations.md](./docs/production-operations.md)
-- [docs/production-deployment.md](./docs/production-deployment.md)
+- [docs/architecture.md](./docs/architecture.md)
- [docs/customer-aws-onboarding.md](./docs/customer-aws-onboarding.md)
- [docs/status-and-limitations.md](./docs/status-and-limitations.md)
- [`infra/terraform/README.md`](./infra/terraform/README.md)
-## Roadmap Direction
-
-- Validate real AWS cost syncs and alert evaluation against live accounts
-- Finalize SES-backed email delivery end to end
-- Continue improving reliability, observability, and operational polish
-
## License
This project is licensed under the terms in [LICENSE](./LICENSE).