Welcome to the Personal Lifecycle Tracker repository. This project manages Renewals, Maintenance, and Warranties for independent users and shared groups, including action summaries, in-app notifications, and scheduled daily morning email digests.
It is governed by the AI-Native Meta-Environment (meta-environment) capability framework and strict zero-host-runtime container standards.
postgres:16-alpine) or SQLite fallback.contracts/openapi.yaml.| Service | Container Port | Host Port (Configurable) | Health / Status Endpoint |
|---|---|---|---|
| Database (PostgreSQL) | 5432 |
5434 (${POSTGRES_PORT:-5434}) |
pg_isready -U postgres -d lifecycle |
| Backend (Dev) | 8000 |
8003 (${BACKEND_PORT:-8003}) |
http://localhost:8003/health |
| Backend Metrics (Prometheus) | 8000 |
8003 (${BACKEND_PORT:-8003}) |
http://localhost:8003/metrics |
| Frontend (Dev) | 3000 |
3003 (${FRONTEND_PORT:-3003}) |
http://localhost:3003/ |
| API Docs (Swagger) | 8000 |
8003 |
http://localhost:8003/docs |
| Interactive ReDoc | 8000 |
8003 |
http://localhost:8003/redoc |
| Production Stack (Caddy) | 80 |
8088 (${PROD_PORT:-8088}) |
http://localhost:8088/health |
| OTel Collector (gRPC) | 4317 |
4327 (${OTEL_GRPC_PORT:-4327}) |
Internal gRPC OTLP receiver |
| OTel Collector (HTTP) | 4318 |
4328 (${OTEL_HTTP_PORT:-4328}) |
http://localhost:4328/v1/traces |
| OTel Metrics (Prometheus) | 8889 |
8899 (${OTEL_METRICS_PORT:-8899}) |
http://localhost:8899/metrics |
| Prometheus Server | 9090 |
9091 (${PROMETHEUS_PORT:-9091}) |
http://localhost:9091 |
| Loki Log Engine | 3100 |
3101 (${LOKI_PORT:-3101}) |
http://localhost:3101/ready |
| Tempo Trace Engine | 3200 |
3201 (${TEMPO_PORT:-3201}) |
http://localhost:3201/ready |
| Grafana UI & Dashboards | 3000 |
3004 (${GRAFANA_PORT:-3004}) |
http://localhost:3004/api/health |
Strict Project Directory Boundary:
..) or sibling directories.Universal Zero-Host-Runtime Mandate:
no host python, no host pip, no host node, no host npm).docker compose.Pre-Flight Port Collision Check:
8003, 3003, 8088) are free:
rtk docker ps --filter "publish=8003"
rtk docker ps --filter "publish=3003"
RTK Command Wrapper:
rtk (e.g. rtk docker compose ps, rtk make test).Start the full stack (backend + frontend) in detached mode:
# Using Makefile
make up
# Or directly with Docker Compose
docker compose up -d --build
Verify service status and health:
# Check status of running containers
make ps
# or: docker compose ps
Both containers will report Up (healthy).
Access the application:
Stream live application logs:
make logs
# Or specific service logs:
docker compose logs -f backend
docker compose logs -f frontend
Stop and clean up containers:
make down
# or: docker compose down -v
Build and run the production image artifacts using Caddy 2 reverse proxy:
docker compose -f docker-compose.prod.yml up -d --build
Verify production endpoints:
Tear down production stack:
docker compose -f docker-compose.prod.yml down -v
Start the independent observability stack (OpenTelemetry Collector, Prometheus, Loki, Tempo, Grafana):
# Using Makefile
make obs-up
# Or directly with Docker Compose
docker compose -f observability/docker-compose.yaml up -d
Verify running status:
make obs-ps
# or: docker compose -f observability/docker-compose.yaml ps
Access observability dashboards & engines:
admin / admin)Stream observability logs:
make obs-logs
# Or specific component:
docker compose -f observability/docker-compose.yaml logs -f otel-collector
Tear down observability stack:
make obs-down
# or: docker compose -f observability/docker-compose.yaml down -v
All verification commands execute in isolated container environments:
make test
make test-backend
# Or directly via Compose:
docker compose run --rm backend pytest
make test-frontend
# Or directly via Compose:
docker compose run --rm frontend npm test
make lint
# Or directly via Compose:
docker compose run --rm frontend npm run lint
make test-e2e
# Or directly via Compose:
docker compose run --rm e2e
Create an optional .env file in the project root to override defaults:
# Host port mappings
BACKEND_PORT=8003
FRONTEND_PORT=3003
PROD_PORT=8088
POSTGRES_PORT=5434
# Application environment
APP_ENV=development
PYTHONUNBUFFERED=1
# Database connection (PostgreSQL default in Compose, or SQLite e.g. sqlite:///./lifecycle.db)
DATABASE_URL=postgresql://postgres:postgres@db:5432/lifecycle
# PostgreSQL service credentials (used when running via Docker Compose)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=lifecycle
# Frontend API routing
VITE_API_URL=http://localhost:8003
VITE_BACKEND_URL=http://backend:8000
To maintain context precision across AI agent sessions, detailed domain knowledge is partitioned into dedicated modular documents:
_docs/team.md — Squad roles (PM, Architect, Developer, QA, On-Call), responsibilities, and handover protocols._docs/process.md — Formal 12-gate lifecycle, testing pyramid, and promotion gates._docs/architecture.md — Component breakdown, container network layout, and service communication.product-spec.md — Functional requirements, domain entities, acceptance criteria, and anti-goals.backlog.md — Atomic task breakdown, statuses, and verification deliverables._docs/telemetry.md — OpenTelemetry tracing, Prometheus metrics, and Loki log correlations.docs/permissions.md — Tool permissions, least-privilege boundaries, and filesystem confinement.docs/demo.md — 6-step interactive verification script for agent capabilities.docs/deployment/README.md — AWS Terraform, CloudFormation, and Render guides..
├── AGENTS.md # Project constitution & instructions
├── README.md # Project overview & documentation
├── Makefile # Docker Compose & containerized IaC automation targets
├── .github/
│ └── workflows/
│ ├── ci.yml # Automated CI/CD pipeline (tests, compose e2e, render deploy)
│ └── promote-dev-to-prod.yml # Manual dev-to-production promotion & release workflow
├── render.yaml # Render Blueprint declarative 1-click deployment
├── docker-compose.yaml # Development multi-app composition
├── docker-compose.prod.yml # Production multi-stage Caddy composition
├── observability/ # Decoupled Observability Compose project
│ ├── docker-compose.yaml # OpenTelemetry Collector, Prometheus, Loki, Tempo, Grafana
│ ├── otel-collector-config.yaml # OTLP pipelines to Tempo, Prometheus, and Loki
│ ├── prometheus.yml # Prometheus scrape configuration
│ ├── loki-config.yaml # Loki filesystem & TSDB storage configuration
│ ├── tempo-config.yaml # Tempo local trace storage configuration
│ ├── .env.example # Configurable port and container overrides
│ ├── README.md # Observability guide, architecture & verification
│ └── grafana/
│ ├── dashboards/ # Pre-provisioned Golden Signals overview dashboard
│ └── provisioning/ # Automated datasources (Loki, Tempo, Prometheus) & dashboards
├── on-call-engineer/ # Autonomous On-Call Incident Responder
│ ├── poll-alerts.py # Observability alert poller (runs every minute)
│ ├── payload-schema.json # JSON schema for normalized incident payloads
│ ├── autonomy-policy.json # Code-enforced autonomy levels & permissions
│ ├── prompt.md # Prompt template for headless coding agent
│ ├── runbook.md # Triage runbook for Prometheus alerts
│ ├── README.md # On-call operating guide & commands
│ ├── scripts/ # Poller, agent invoker & verification scripts
│ └── cloud-simulator/ # Local AWS Serverless On-Call Simulator (SNS, Lambda, Fargate, S3)
├── openapi.yaml # Root API contract
├── contracts/
│ └── openapi.yaml # Frozen canonical contract
├── docs/
│ ├── spec.md # Functional specification & scope
│ └── deployment/ # Production deployment playbooks & architecture
│ ├── README.md # Deployment index & decision matrix
│ ├── render.md # Render Blueprint & Terraform guide
│ ├── aws-terraform.md # AWS EC2 Docker Compose Terraform guide
│ └── aws-cloudformation.md # AWS CloudFormation 1-click guide
├── cloudformation/
│ ├── aws-serverless-lambda.yaml # AWS CloudFormation Serverless (Dev: Lambda + S3 + CloudFront)
│ └── aws-serverless-lambda-prod.yaml # AWS CloudFormation Serverless (Production Copy)
├── render.yaml # Render Blueprint (Dev Environment)
├── render.prod.yaml # Render Blueprint (Production Environment Copy)
├── terraform/
│ ├── aws/ # AWS Terraform Serverless (Dev: Lambda + S3 + CloudFront + ECR)
│ │ ├── versions.tf
│ │ ├── variables.tf
│ │ ├── lambda.tf
│ │ ├── s3_cloudfront.tf
│ │ ├── ecr.tf
│ │ ├── oidc.tf
│ │ ├── on-call-responder.tf
│ │ ├── scheduler.tf
│ │ ├── outputs.tf
│ │ └── terraform.tfvars.dev
│ ├── aws-prod/ # AWS Terraform Serverless (Production Copy)
│ │ ├── versions.tf
│ │ ├── variables.tf
│ │ ├── lambda.tf
│ │ ├── s3_cloudfront.tf
│ │ ├── ecr.tf
│ │ ├── oidc.tf
│ │ ├── on-call-responder.tf
│ │ ├── scheduler.tf
│ │ ├── outputs.tf
│ │ └── terraform.tfvars.prod
│ ├── render/ # Render Terraform (Dev Environment: free plan)
│ │ ├── versions.tf
│ │ ├── variables.tf
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── terraform.tfvars.dev
│ └── render-prod/ # Render Terraform (Production Environment Copy: starter plan)
│ ├── versions.tf
│ ├── variables.tf
│ ├── main.tf
│ ├── outputs.tf
│ └── terraform.tfvars.prod
├── backend/
│ ├── Dockerfile # Python 3.11 base image with healthchecks
│ ├── requirements.txt # Backend dependencies
│ ├── pyproject.toml # Pytest configuration
│ ├── app/ # FastAPI application & routers
│ └── tests/ # Backend pytest test suite
├── frontend/
│ ├── Dockerfile # Multi-stage: dev, builder, prod (Caddy)
│ ├── Caddyfile # Production Caddy 2 reverse proxy config
│ ├── package.json # Frontend dependencies & scripts
│ ├── vite.config.ts # Vite server, host & backend proxy config
│ └── src/ # React components, UI views & services
└── e2e/
├── Dockerfile # Microsoft Playwright v1.50 container
├── package.json # Playwright dependencies
├── playwright.config.ts # Test configuration targeting dev stack
├── helpers.ts # Test reset helper and auth utilities
├── auth.spec.ts # Authentication & account switching tests
├── groups.spec.ts # Shared groups & member management tests
├── lifecycle-items.spec.ts# Renewal/maintenance/warranty CRUD & filters
├── reminders-digest.spec.ts# Reminders drawer & email digest tests
└── spec-compliance.spec.ts# Comprehensive Section 6 acceptance journey
Execute all validations and formatting inside Docker without host dependencies:
render.yaml | Prod Blueprint Copy: render.prod.yamlterraform/render/ | Prod Terraform Copy: terraform/render-prod/make tf-validate-render and make tf-validate-render-prodterraform/aws/ | Prod Terraform Copy: terraform/aws-prod/cloudformation/aws-serverless-lambda.yaml | Prod CloudFormation Copy: cloudformation/aws-serverless-lambda-prod.yamlmake tf-validate (validates all Terraform environments) and make cf-validate (validates both CloudFormation templates)The CI/CD pipeline decouples image creation from serving:
Build Stage (build-and-push-ecr):
backend and frontend).YYYYMMDD-HHMMSS-shortsha pattern (e.g. 20260818-163457-83242da) and pushes to Amazon ECR./personal-lifecycle/${TARGET_ENV}/image_tag).Deploy Stage (deploy):
docker compose -f docker-compose.prod.yml up -d --no-build). Zero image building occurs on the deployment host./health endpoint (HTTP 200).Dev to Production Image Promotion (promote-dev-to-prod.yml):
YYYYMMDD-HHMMSS-shortsha), semantic release tag (vX.Y.Z), and prod-latest.regularly commit code to git
This user has signed up for the new AWS experience. This experience lets you sign into AWS using a social provider and requires the following additional context.
Where this guidance conflicts with the project's own instructions, the project's instructions take precedence.
us-east-1. A user can create a CloudFront distribution pointing to their project-region Lambda function URL or API Gateway. However, Lambda and API Gateway themselves MUST NOT be created in us-east-1 — they must be in the project Region.eu-north-1 specifically: Amazon Rekognition, Amazon Textract, Amazon Personalize, AWS App Runner are not available in that Region.aws freetier get-account-plan-stateYou CAN update this rule file to save a user's help_level.
Constraints for each level:
LOW:
MEDIUM:
HIGH: