Understand the codebase and start contributing:

1. Quick Start Index - Orientation (5m)
2. Architecture Guide - Deep dive (15m)
3. API Reference - All 18 endpoints
4. Local Dev Setup - Environment config

Operational guidance for production:

1. Deployment Guide - Local to Cloud
2. Config Reference - Env var tuning
3. Capacity Plan - Scaling limits
4. Runbooks - Incident procedures

Fast response when things break:

1. Incident Runbooks - Step-by-step fixes
2. Troubleshooting Guide - Root cause diagnosis
3. Alert Definitions - What each alert means

Vybe follows the strict RESTful specifications required for the MLH Automated Test Suite.

• GET /health - Core health probe. Returns 200 OK with {"status": "ok"}.
• GET /ready - Readiness probe. Verifies active database and cache connectivity.

• POST /users - Create a new user account. Returns 201 Created.
• GET /users - List all users (Supports pagination ?page=x&per_page=y).
• GET /users/<id> - Retrieve metadata for a specific user.
• PUT /users/<id> - Update user profile attributes.
• POST /users/bulk - Bulk import users via multipart/form-data CSV upload.

• POST /urls - Shorten a new original URL. Returns 201 Created with a short_code.
• GET /urls - List generated links (Supports filtering ?user_id=1).
• GET /urls/<id> - Retrieve deep metadata for a specific short link.
• PUT /urls/<id> - Update link status (is_active) or title.
• GET /<short_code> - The high-performance redirect route. Returns 302 Found.

• GET /events - Stream high-density click logs and metadata for observability.

ⓘ NOTE Create a .env file in the root before spinning up independent instances manually. If omitted, docker compose defaults will govern gracefully.

1. DNS & Proxying: Map your root domain (A record) to the targeted load balancer IP. Ensure the Proxy status is Proxied (Orange Cloud) to inherit Cloudflare's native DDoS protections globally.
2. SSL/TLS Mode: Configure encryption logic strictly to Full (Strict).
3. Edge Rules: Enforce strict Rate Limiting (Rate Limiting Rules) on the /auth/login and /links/create routes to prevent brute-force PgSQL exhaustion before traffic physically reaches your Droplets.

1. Provision 3 Isolated Droplets (Ubuntu 24.04 LTS):

   • App Droplet 1: (Backend + Nginx)
   • App Droplet 2: (Backend + Nginx)
   • Observability Droplet: (Prometheus, Grafana, Loki, Alertmanager, OpenTelemetry)

2. Network Integrity (Cloud Firewalls):

   • Lock ingress traffic tightly. Only whitelist trusted Cloudflare IP ranges to access Port 80 / 443 on App Droplets.
   • Open ports 3000/9090 temporarily strictly bridging to the Observability VPN hub.

1. Provision a DigitalOcean Managed PostgreSQL Cluster and Managed Redis Instance.
2. Isolate them inside a localized VPC Network. Guarantee that only your specifically authenticated App Droplets own the VPC Private IPs to communicate.

# 1. Clone & Set Boundaries
git clone https://github.com/Invariants0/Vybe.git && cd Vybe
cp .env.example .env 
# (Strictly define DO_HOST_1, DO_HOST_2, DB endpoints)

# 2. Spin Clusters
docker compose -f docker-compose.prod.yml up -d --build

# 3. Validation Checkout
curl http://localhost/health/ready

Vybe implements robust architectural blueprints resolving the Reliability and Scalability metrics natively:

• Graceful Degradation (Silent Fails): If the external analytics database fails to mount, the /urls/:code redirect continues flawlessly. Rather than throwing a 500 Internal Server Error, the execution securely wraps telemetry dumps inside detached try/except logic ensuring primary flow features operate untouched.
• Pydantic Hardening: All JSON payload requests are universally restricted (e.g., title parameters bounded safely strictly under 255 chars). This decisively defends against structural data poisoning rendering 422 Unprocessable instead of manipulating the runtime into unbounded memory exhaustion.
• Strict Boundaries (404 vs 409): The controller layers dynamically verify explicit Foreign Keys (user_id presence via get_or_none) before engaging active DB IntegrityError cascades. This translates structural constraints securely into expected REST protocol 404 Not Found messages preventing hard DB lock-ups.
• Zero Race Conditions: Generating unique shortened codes doesn't strictly rely on sequential find() checks (which continuously yield Check-Then-Act failures across async nodes). Vybe aggressively pushes iterative hooks via a peewee.IntegrityError looped safety net to definitively guarantee 100% collision resolution asynchronously.

• Validate that docker daemon is operating without memory ceilings.
• Ensure ports 5000 (API) and 3001 (Grafana) aren't historically occupied. Execute sudo lsof -i :5000.

• Verify .env values correctly define $DATABASE_HOST. If operating local, ensure it reads localhost instead of the compose alias db.
• Check pg logs: docker compose ps db OR docker logs vybe-db.

• If logs aren't emitting to Loki / JSON sinks, check the Gunicorn mount volume access rights (chmod 644 logs/app.log).
• Inspect the output: A proper log includes ts, level, logger, event, and service.

⚠️ WARNING
Never perform manual DELETE operations on the PostgreSQL urls table in production. This drastically alters cache mapping consistency.

Scenario: Postgres Database Goes Down

Symptom: P95 latency spikes massively and 500 metrics trigger. Response: Vybe utilizes silent fails. Secondary metrics and tracking mechanisms will be bypassed entirely to aggressively keep raw 302 redirects executing optimally. Wait for automatic container restarts or force docker compose restart db.

Scenario: Foreign Key Integrations Fail

Symptom: Creation endpoints start tossing 409 Conflict. Response: Ensure API invocations accurately check user_id context.