Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/architecture/00-baseline/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

A URL shortener accepts a long URL and returns a short, human-shareable alias that redirects to the original. The system's primary job is redirection — it is not a metadata store, analytics platform, or user management system. Redirects are perceived as part of normal page navigation; any latency is user-visible. The system must therefore be optimised heavily for the read (redirect) path, while keeping the write (create) path simple and correct.

The deployment target is `us-east-1` (single region). The API and short URL redirects are served at `go.buffden.com` (ALB → EC2 → Spring Boot); the Angular SPA is hosted at `tinyurl.buffden.com` (S3 + CloudFront). v1 establishes a production-minimal baseline. v2 evolves it to handle higher scale and reliability requirements without changing the deployment model.
The deployment target is `us-east-1` (single region). The API and short URL redirects are served at `go.buffden.com` (EC2 → Spring Boot); the Angular SPA is hosted at `tinyurl.buffden.com` (S3 + CloudFront). v1 establishes a production-minimal baseline. v2 evolves it to handle higher scale and reliability requirements without changing the deployment model.

---

Expand Down Expand Up @@ -102,7 +102,7 @@ These decisions are locked before v1 implementation begins. Changing them requir

Goal: ship the smallest correct system.

- Components: DNS → Load balancer → Nginx → App servers → PostgreSQL
- Components: DNS → Nginx → App servers → PostgreSQL
- No cache required in v1; DB handles up to 5K QPS peak
- Rate limiting at Nginx level (coarse per-IP throttle on `POST /api/urls`)
- No soft delete required (optional `is_deleted` field, deferred to v2)
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/00-baseline/adr/ADR-002-scaling-approach.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The system is read-heavy (99:1 read/write ratio in v1, 95:5 in v2). The redirect

## Decision

**v1**: Scale application servers **horizontally** behind a load balancer. Keep the database as a **single PostgreSQL primary** (vertical scaling + indexing). No cache required.
**v1**: Scale application servers **horizontally** behind Nginx. Keep the database as a **single PostgreSQL primary** (vertical scaling + indexing). No cache required.

**v2**: Add **Redis cache-aside** on the redirect path (> 90% cache hit target) to absorb the 20K QPS peak without overloading the DB. Enable app autoscaling on CPU + P95 latency. Add a DB read replica only if cache miss pressure on the primary becomes measurable.

Expand All @@ -28,7 +28,7 @@ The system is read-heavy (99:1 read/write ratio in v1, 95:5 in v2). The redirect
## Consequences

- Application instances must be **fully stateless** — no in-process session or shared memory.
- Load balancer and health checks are required infrastructure from v1.
- Nginx and health checks are required infrastructure from v1.
- The trigger for adding read replicas is a **measured metric**, not an upfront decision.
- v2 introduces Redis as a new operational failure domain; the redirect path must degrade gracefully when Redis is unavailable (fall back to DB, apply stricter rate limiting).

Expand Down
7 changes: 3 additions & 4 deletions docs/architecture/00-baseline/poc-requirements-baseline.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Version 1:

- Client (browser).
- DNS Resolution.
- Load balancer (L4 or L7).
- Nginx (TLS termination + reverse proxy).
- Stateless application servers.
- Storage system (short -> original mapping) SQL.
- Optional in-memory cache for hot keys.
Expand Down Expand Up @@ -153,7 +153,7 @@ Reason:

- Read-heavy workload (80/20).
- Stateless redirect logic.
- App instances can scale independently behind load balancer.
- App instances can scale independently behind Nginx.
- DB initially vertically scaled, later read-replicated if needed.

Avoid premature sharding at this stage.
Expand All @@ -166,8 +166,7 @@ Avoid premature sharding at this stage.
| ------------- | ------------------ | ---------------------- | ---------------------------- |
| DB | Slow query | Redirect latency spike | Proper indexing |
| DB | Down | All redirects fail | Replication + failover |
| App | Crash | Partial 5xx errors | Multiple instances behind LB |
| Load Balancer | Misroute | Partial outage | Health checks |
| App | Crash | Partial 5xx errors | Multiple instances, health checks |
| DNS | Resolution failure | Full outage | DNS caching + low TTL |
| Cache | Miss storm | DB overload | Rate limiting + TTL |

Expand Down
Loading
Loading