# Architecture Decision Records (ADR)

This document tracks all significant architectural decisions made during the project, including rationale and trade-offs.

---

## ADR-001: Cloud Provider - AWS

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Use Amazon Web Services (AWS)

**Rationale**:
- Industry-standard cloud provider with comprehensive service portfolio
- Access to managed services when beneficial
- Strong ecosystem and community support
- Terraform has excellent AWS provider support

---

## ADR-002: Infrastructure as Code - Terraform

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Use Terraform for infrastructure provisioning

**Rationale**:
- Declarative approach (aligns with project philosophy)
- Industry standard for cloud infrastructure
- Excellent AWS provider
- State management enables reproducibility

**Scope**: VPC, EC2, Security Groups, S3, Route 53

---

## ADR-003: Configuration Management - Ansible

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Use Ansible for system configuration (kept minimal)

**Rationale**:
- Avoids problematic user-data scripts (bad experience with debugging)
- Idempotent - can re-run if setup fails
- Real-time output visibility via SSH
- Professional separation of concerns: Terraform (infra) → Ansible (config) → Docker (apps)

**Scope**: Install Docker, configure system basics, setup firewall
**Philosophy**: Keep Ansible simple - no fancy roles or complexity

**Alternative Considered**: User-data scripts - rejected due to debugging difficulty and one-shot nature

---

## ADR-004: Application Deployment - Docker + Docker Compose

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Use Docker with Docker Compose for application orchestration

**Rationale**:
- Fully declarative (docker-compose.yml)
- Easy to test locally (dev/prod parity)
- Simple version control and updates
- Gitea has official Docker images
- Portable and reproducible

**Scope**: Gitea, nginx, PostgreSQL, monitoring stack (later)

---

## ADR-005: Database - Self-Hosted PostgreSQL in Docker

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: PostgreSQL container, not RDS

**Rationale**:
- Simpler architecture (everything in docker-compose.yml)
- Shows ability to build and manage backups ourselves
- More control over configuration
- Cost-effective
- PostgreSQL is Gitea's recommended database

**Trade-offs**:
- **Pros**: Greater control, cost-effective, simpler architecture
- **Cons**: Requires custom backup automation and testing

**Backup Strategy**: Custom scripts with pg_dump to S3 (detailed in backup phase)

**Future Consideration**: For higher availability requirements or larger scale, RDS would provide managed backups, point-in-time recovery, and Multi-AZ deployment

---

## ADR-006: Reverse Proxy - Nginx

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Nginx as reverse proxy

**Rationale**:
- Lightweight and performant
- Simple configuration for basic proxying
- Industry standard
- Works well in Docker

**Scope**: SSL termination, proxy to Gitea, HTTP→HTTPS redirect

---

## ADR-007: SSL Certificates - Let's Encrypt

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Let's Encrypt with certbot

**Rationale**:
- Free, automated, trusted certificates
- Widely accepted by all browsers (no certificate warnings)
- Auto-renewal reduces operational burden
- Industry-standard solution for SSL/TLS

**Requirement**: Valid domain name pointing to server

---

## ADR-008: Update Automation - Watchtower

**Date**: 2026-06-08  
**Status**: Accepted

**Decision**: Watchtower for Docker image updates

**Rationale**:
- Purpose-built for Docker environments
- Simple to configure (runs as container)
- Automatic image updates on schedule
- Minimal complexity

**Scope**: Monitor and update Gitea, nginx, and other containers

---

## ADR-009: Monitoring - Prometheus + Grafana

**Date**: 2026-06-08  
**Status**: Accepted (implementation later)

**Decision**: Prometheus for metrics, Grafana for visualization

**Rationale**:
- Industry standard monitoring stack
- Powerful querying with PromQL
- Rich visualization and alerting capabilities
- Strong community and pre-built dashboards

**Note**: To be implemented in later phase

---

## ADR-010: Logging - Loki + Promtail

**Date**: 2026-06-08  
**Status**: Accepted (implementation later)

**Decision**: Loki for log aggregation, Promtail for collection

**Rationale**:
- Lightweight compared to ELK stack
- Integrates with Grafana (single pane of glass)
- Good fit for Docker environments

**Note**: To be implemented in later phase

---

## ADR-011: Backup Strategy - Custom Scripts + S3

**Date**: 2026-06-08  
**Status**: Accepted (implementation later)

**Decision**: Bash scripts with pg_dump and AWS S3

**Rationale**:
- Simple and maintainable
- Full control over backup process and scheduling
- S3 provides highly durable storage (99.999999999%)
- Easy to test and validate restore procedures

**Scope**: 
- Database backups (pg_dump)
- Gitea repository data
- Configuration files
- Automated scheduling with cron

**Note**: Details to be designed in backup phase

---

## Technology Stack Summary

| Layer | Technology | Rationale |
|-------|-----------|-----------|
| **Cloud** | AWS | Industry standard |
| **Infrastructure** | Terraform | Declarative IaC |
| **Configuration** | Ansible (minimal) | System setup, avoids user-data |
| **Compute** | EC2 | Flexible VM hosting |
| **Application** | Docker Compose | Declarative orchestration |
| **Database** | PostgreSQL (Docker) | Self-managed, shows control |
| **Reverse Proxy** | Nginx | Lightweight, standard |
| **SSL** | Let's Encrypt | Free, automated, professional |
| **DNS** | Route 53 | AWS-native |
| **Updates** | Watchtower | Docker-native automation |
| **Backups** | Scripts + S3 | Custom, controlled |
| **Monitoring** | Prometheus + Grafana | Industry standard |
| **Logging** | Loki + Promtail | Lightweight, integrated |

---

## Core Principles

1. **Simplicity First**: Avoid overengineering
2. **Declarative Over Imperative**: Terraform, Docker Compose
3. **Infrastructure as Code**: Everything version-controlled
4. **Show Control**: Build things ourselves where it demonstrates skill
5. **Professional**: Production-grade practices