small fix, don't worry about it

docs/archive/research/dashboard.md

@@ -0,0 +1,385 @@
+1️⃣ What the Railway Dashboard Is
+
+Railway is a PaaS (Platform as a Service).
+
+The dashboard is where you:
+
+Create services (apps, APIs, workers)
+
+Add databases
+
+Connect GitHub repos
+
+Configure env variables
+
+View logs & metrics
+
+Define networking between services
+
+Instead of showing raw Kubernetes or Docker Compose, Railway abstracts everything into a visual canvas.
+
+2️⃣ What This “Canvas” Actually Is
+
+The key part in your HTML:
+
+<div class="react-flow ...">
+
+
+That tells us immediately:
+
+👉 They’re using React Flow — a React library for building node-based editors.
+
+React Flow powers:
+
+Node graphs
+
+Drag & drop canvases
+
+Visual connections
+
+Zoom/pan
+
+Edges with arrows
+
+So this canvas = a React Flow graph editor customized to represent infrastructure.
+
+3️⃣ Architecture of the Canvas
+
+Here’s what’s happening internally:
+
+A) Root Layout
+stack-container
+nested-canvas
+canvas-container
+
+
+This is:
+
+Grid layout
+
+Responsive behavior
+
+Sidebar + center canvas layout
+
+Mobile floating button
+
+They’re using:
+
+Tailwind CSS
+
+CSS Grid
+
+Dark mode variants
+
+Utility classes
+
+Very modern stack.
+
+B) The Graph Engine (React Flow)
+
+This part:
+
+<div class="react-flow__viewport"
+     style="transform: translate(306px, 279px) scale(1);">
+
+
+This means:
+
+The canvas supports panning (translate X/Y)
+
+It supports zooming (scale)
+
+Entire graph is rendered inside a transform container
+
+So when you drag around → it updates the transform.
+When you zoom → scale changes.
+
+Classic infinite canvas technique.
+
+C) Nodes
+
+Example:
+
+<div class="react-flow__node react-flow__node-empty">
+
+
+Nodes represent:
+
+GitHub repo
+
+Database
+
+Docker image
+
+Function
+
+Bucket
+
+Empty service
+
+Each node = React component.
+
+Internally Railway likely stores something like:
+
+{
+  id: "service_123",
+  type: "github",
+  position: { x: 120, y: 400 },
+  data: {
+    repo: "...",
+    env: {...}
+  }
+}
+
+
+React Flow renders this declaratively.
+
+D) Edges (Connections)
+
+This part:
+
+Edges are rendered in SVG.
+
+You also saw:
+
+<marker id="arrowhead">
+
+
+That defines arrowheads for:
+
+Normal connection
+
+Staged
+
+Selected
+
+Network
+
+Alternative
+
+So edges are dynamic SVG paths with markers attached.
+
+4️⃣ What the Command Palette Is
+
+This section:
+
+<input placeholder="What would you like to create?" cmdk-input>
+
+
+This is a command palette UI.
+
+Looks like they use:
+
+👉 cmdk (a React command menu library)
+
+So when you type:
+
+“github”
+
+“database”
+
+“docker”
+
+It filters options.
+
+Selecting one → creates a new node in the graph.
+
+This is very similar to:
+
+Linear
+
+Vercel
+
+Raycast UI pattern
+
+5️⃣ How the Dashboard Works Conceptually
+
+The visual canvas is just a frontend representation of backend state.
+
+Behind the scenes:
+
+Step 1 — You Add a Service
+
+→ Frontend sends API request:
+
+POST /services
+
+Step 2 — Railway Backend
+
+Likely:
+
+Creates container definition
+
+Assigns internal network
+
+Stores graph structure in DB
+
+Triggers deployment pipeline
+
+Step 3 — Infra Layer
+
+Under the hood Railway probably uses:
+
+Containers (Docker)
+
+Orchestration (likely Kubernetes or custom scheduler)
+
+Internal networking mesh
+
+Volume storage
+
+Load balancing
+
+The canvas is just a visual abstraction over:
+
+Containers + Networks + Volumes + Environment Variables
+
+6️⃣ What “Stack Container” Means
+id="stack-container-root"
+
+
+A “stack” in Railway terms =
+
+A collection of services that form one project.
+
+Like:
+
+API
+
+Database
+
+Redis
+
+Worker
+
+Cron
+
+All connected together.
+
+This is similar to:
+
+Docker Compose stack
+
+Kubernetes namespace
+
+Vercel project
+
+7️⃣ The Networking Animation
+
+You saw:
+
+@keyframes networkFlowEgress
+@keyframes networkFlowIngress
+
+
+That’s animated edge flow.
+
+Meaning:
+
+When traffic flows between services
+
+They animate dots moving across edges
+
+This gives visual feedback like:
+“API → Database”
+
+Very clean UX detail.
+
+8️⃣ What the Floating Button Is
+<button class="sm:hidden fixed right-4 bottom-4">
+
+
+That’s the mobile "Add Service" button.
+
+On small screens:
+
+Canvas hides
+
+Floating action button appears
+
+Material-inspired design pattern.
+
+9️⃣ So What Is This Canvas Technically?
+
+It is:
+
+A React Flow–powered infrastructure graph editor that maps frontend node/edge state to backend service configuration.
+
+Or simpler:
+
+👉 A visual Docker/Kubernetes orchestrator UI.
+
+🔟 If You Built This Yourself
+
+Given your experience (Go backend + Railway + infra + React):
+
+You’d need:
+
+Frontend:
+
+React
+
+React Flow
+
+Tailwind
+
+Command palette (cmdk)
+
+State manager (Zustand likely)
+
+Backend:
+
+Service registry
+
+Deployment engine
+
+Container runtime control
+
+Network layer
+
+Logs streaming
+
+Optional:
+
+WebSocket for real-time deployment status
+
+Event-driven state updates
+
+⚙️ Why This Design Is Smart
+
+Non-dev friendly
+
+Infrastructure becomes visual
+
+Encourages service-based architecture
+
+Makes networking intuitive
+
+Looks “modern infra SaaS”
+
+Railway basically turned:
+
+docker-compose.yml
+
+
+into:
+
+a draggable visual graph
+
+🚀 Big Picture
+
+Railway dashboard =
+
+React app
+
+React Flow canvas
+
+Command palette-driven node creation
+
+SVG-based edge system
+
+Tailwind-based design
+
+Backend infra orchestration API
+
+It’s a visual abstraction over cloud container orchestration.

docs/archive/research/inspo.md

@@ -0,0 +1,63 @@
+# 🚆 What the Railway Dashboard Is
+
+The Railway dashboard is the main web interface for managing your Railway cloud projects. It’s essentially your control panel where you can see, organize, configure, and monitor everything you’re hosting on Railway — services, deployments, databases, environments, logs, metrics, and more.
+
+You typically land on the dashboard after signing into your Railway account. It’s the central hub that gives you a high-level view of all your projects and infrastructure.
+
+## 🧠 What It Lets You Do
+
+### 📦 1. See and Manage Projects
+
+The dashboard shows all projects you own or belong to, sorted by recent activity.
+
+Each project can contain multiple services (like a web app, API, worker, database).
+
+From the dashboard you can click into each project to manage details.
+
+### ⚙️ 2. Configure and Deploy Services
+
+Within a project, you can link code repositories (GitHub) or container images.
+
+Railway handles build and deploy processes automatically — including automatic configuration for many languages/frameworks.
+
+Deployments are shown with statuses (building, deployed, errors).
+
+### 📊 3. Monitoring & Observability
+
+View logs and performance metrics (CPU, memory, network, disk usage) per service.
+
+You can create dashboards with charts and custom widgets for things like request rates or error logs.
+
+Set alerts for thresholds (like high CPU or errors) and receive notifications via Slack, Discord, email, and more.
+
+### 🔐 4. Manage Secrets & Environment Variables
+
+Set configuration variables (like API keys or database URLs) that your services use.
+
+Variables can be scoped to services or shared across the entire project.
+
+### 🔁 5. Staging & Environments
+
+Railway supports multiple environments (dev, staging, prod).
+
+You can preview changes in separate environments and promote or rollback deployments with a click.
+
+### 📚 6. Templates & One-Click Deploy
+
+Access a library of templates to quickly deploy common stacks (e.g., databases with backend, analytics tools).
+
+Templates auto-provision services and databases as a project.
+
+## 🧑‍💻 How It Works (Behind the Scenes)
+
+Railway’s dashboard directly reflects the state of your projects by talking to its API backend (the same API used by their CLI). It pulls data like:
+
+Project list and status
+
+Deployment logs and history
+
+Resources (CPU, memory, traffic)
+
+Environment and configuration values
+
+Changes you make in the dashboard (like redeploying or updating variables) are sent back to the Railway API and applied to your infrastructure.

docs/archive/research/inspo2.md

@@ -0,0 +1,254 @@
+# 🧩 What the Project Page Is
+
+The Project page represents one isolated application environment on Railway.
+
+Think of a project as:
+
+> A self-contained box that holds all services, databases, configs, deployments, logs, metrics, and environments for one product or system.
+
+### Example Structure
+
+```
+One project = spark-screen
+├── Go backend
+├── Frontend (Vite/Solid)
+├── PostgreSQL
+├── Redis
+├── Worker / cron
+└── Preview + Production environments
+```
+
+## 🗺️ Main Layout of the Project Page
+
+Visually, the project page is built around a canvas + side panels model.
+
+### 1️⃣ Project Canvas (Center)
+
+This is the graph view you see first.
+
+### What it shows:
+
+- **Each service as a card** (app, db, worker, etc.)
+- **Lines showing relationships** (e.g. `backend → database`)
+- **Deployment status per service**
+
+### Each card usually displays:
+
+- **Service name**
+- **Source** (GitHub repo, Dockerfile, template)
+- **Current deployment status** (running, building, failed)
+- **Quick access to logs & settings**
+
+> 👉 This canvas is not just visual — it reflects actual runtime dependencies.
+
+### 2️⃣ Services (Core Units)
+
+Each box on the canvas is a Service.
+
+A service can be:
+
+- **Web app** (Go, Node, Bun, Python, etc.)
+- **Background worker**
+- **Cron job**
+- **Database** (Postgres, Redis, MySQL)
+- **Custom Docker container**
+
+Clicking a service opens its Service Detail Panel.
+
+## 🔍 Inside a Service (Very Important)
+
+When you click a service, you get several tabs:
+
+### ⚙️ Settings
+
+This is the brain of the service.
+
+You configure:
+
+- **Source**
+  - GitHub repo (via GitHub App)
+  - Branch
+  - Root directory
+- **Build**
+  - Build command
+  - Start command
+  - Dockerfile (optional)
+- **Resources**
+  - CPU / RAM limits
+- **Networking**
+  - Public domain
+  - Internal service-to-service URLs
+
+> **How it works:** Any change here triggers a new deployment. Railway stores this config and applies it at runtime.
+
+### 🔐 Variables (Environment Variables)
+
+This is where Railway shines.
+
+Key–value environment variables
+
+Can be:
+
+- **Service-specific**
+- **Shared across the project**
+- **Environment-scoped** (prod / preview)
+
+### Examples:
+
+```
+DATABASE_URL
+REDIS_URL
+JWT_SECRET
+PORT
+```
+
+
+> **Behind the scenes:**
+>
+> - Injected into the container at runtime
+> - Never hardcoded into images
+> - Securely stored and masked in UI
+
+### 📦 Deployments
+
+This tab shows:
+
+- **Full deployment history**
+- **Commit hash** (if GitHub)
+- **Build logs**
+- **Runtime logs**
+- **Rollback button**
+
+> **How it works:**
+>
+> 1. Git push (or manual deploy)
+> 2. Railway pulls code
+> 3. Builds container (Railpack or Docker)
+> 4. Starts new instance
+> 5. Old one is replaced (zero-downtime when possible)
+
+### 📜 Logs
+
+### Real-time logs:
+
+- **stdout / stderr**
+- **Build logs**
+- **Runtime errors**
+
+Logs are:
+
+- **Per-service**
+- **Per-deployment**
+- **Streamed live from containers**
+
+> This is basically `docker logs` but cloud-native.
+
+### 📊 Metrics
+
+### Per-service metrics:
+
+- **CPU usage**
+- **Memory usage**
+- **Network traffic**
+- **Disk usage** (for DBs)
+
+This helps you:
+
+- **Detect leaks**
+- **Decide when to optimize**
+- **Understand cost drivers**
+
+## 🧱 Databases Inside a Project
+
+Databases are first-class services, not addons.
+
+When you add:
+
+- **PostgreSQL**
+- **Redis**
+- **MySQL**
+
+Railway:
+
+- **Provisions it**
+- **Injects connection URLs**
+- **Handles backups** (plan-dependent)
+
+Databases:
+
+- **Appear on the same canvas**
+- **Can be linked to multiple services**
+- **Expose internal connection strings only**
+
+### Database Benefits
+
+- **Easy setup**
+- **Managed backups**
+- **Internal connection strings**
+
+## 🌍 Environments (Prod, Preview, Dev)
+
+Each project can have multiple environments.
+
+### Common setup:
+
+- **Production** – live app
+- **Preview** – per-PR deployments
+- **Development** – testing
+
+### What changes per environment:
+
+- **Variables**
+- **Domains**
+- **Deployments**
+- **Scaling**
+
+> This is not separate projects — it's logical isolation inside one project.
+
+## 👥 Project-Level Controls
+
+At the project level (not service-level):
+
+### 👤 Members & Permissions
+
+- **Invite teammates**
+- **Control access** (admin / developer)
+
+### 🔔 Notifications
+
+- **Deploy failures**
+- **Usage alerts**
+- **Service crashes**
+
+### 💳 Usage & Billing
+
+- **CPU hours**
+- **RAM hours**
+- **Network**
+- **Cost per service**
+
+## 🧠 How the Project Page Works Internally
+
+Under the hood:
+
+- **The UI talks to the Railway API**
+- **Every service = container + config**
+- **Every deploy = immutable container version**
+- **Variables = injected at runtime**
+- **Services communicate via private internal network**
+
+> So the project page is essentially: a visual orchestrator for containers, deployments, configs, and environments
+
+## 🧠 Mental Model (Best Way to Think About It)
+
+If Docker Compose had:
+
+- **A UI**
+- **GitHub auto-deploys**
+- **Built-in databases**
+- **Metrics**
+- **Logs**
+- **Secrets**
+- **Environments**
+
+> 👉 That's the Railway project page.

docs/archive/research/project.md

@@ -0,0 +1,263 @@
+# Self-Hosted PaaS on Proxmox (Railway-like Platform)
+
+A fully self-hosted, open-source Platform-as-a-Service designed to run on top of **Proxmox infrastructure**, providing a Railway-like developer experience: Git-based deployments, container orchestration, automatic scaling, load balancing, and observability — all under your control.
+
+---
+
+## 🎯 Goals
+
+- Railway-like UX, fully self-hosted
+- Built primarily on **Proxmox + Docker**
+- Horizontal scaling across multiple VMs/LXCs
+- Agent-based orchestration (no Kubernetes required)
+- Git-driven deploys
+- Production-grade networking, metrics, and reliability
+
+---
+
+## 🧱 Core Architecture
+
+- **Control Plane**: Central API + scheduler
+- **Node Agents**: Lightweight daemons running on each VM/LXC
+- **Execution Layer**: Docker containers
+- **Networking**: Traefik reverse proxy & load balancer
+- **State Layer**: Externalized databases and caches
+
+---
+
+## 🧠 Technology Stack
+
+### Backend / Control Plane
+- **Go (primary language)**
+  - Scheduler
+  - Orchestration logic
+  - API server
+  - Scaling engine
+- **Python (auxiliary tooling)**
+  - Metrics processing
+  - Background jobs
+  - Scripts where Go is impractical
+- **Rust (performance-critical components)**
+  - Node agent (optional)
+  - Low-level system monitoring
+  - High-throughput data collectors
+
+---
+
+### Frontend / Dashboard
+- **Bun**
+  - Package manager
+  - Runtime for tooling & scripts
+  - [Documentation](https://bun.sh/)
+- **Vite**
+  - Fast frontend build system
+  - [Documentation](https://vitejs.dev/)
+- **React 18**
+  - Modern UI framework with hooks and concurrent features
+  - [React Documentation](https://react.dev/)
+- **TypeScript (TS / TSX)**
+  - Strict typing
+  - Shared contracts with backend
+  - [Documentation](https://www.typescriptlang.org/)
+- **Tailwind CSS**
+  - Utility-first CSS framework
+  - Rapid UI development with design tokens
+  - [Documentation](https://tailwindcss.com/)
+- **shadcn/ui**
+  - Beautiful, accessible component library built on Radix UI
+  - [Documentation](https://ui.shadcn.com/)
+- **Lucide React**
+  - Beautiful icon library for React
+  - [Documentation](https://lucide.dev/)
+
+**Documentation:**
+- [React 18](https://react.dev/)
+- [Vite](https://vitejs.dev/)
+- [Tailwind CSS](https://tailwindcss.com/)
+- [shadcn/ui](https://ui.shadcn.com/)
+- [Lucide React](https://lucide.dev/)
+- [React Hook Form](https://react-hook-form.com/)
+- [TanStack Query](https://tanstack.com/query/latest)
+
+---
+
+### Infrastructure & Runtime
+- **Docker**
+  - Container runtime
+  - Image builds & execution
+- **Docker Compose / Custom Orchestrator**
+  - Service definitions
+  - Replica management
+- **Traefik**
+  - Reverse proxy
+  - Automatic service discovery
+  - TLS & routing
+- **Proxmox**
+  - VM & LXC orchestration
+  - Compute isolation
+  - Infrastructure backbone
+
+---
+
+### Data & State
+- **PostgreSQL**
+  - Persistent platform state
+  - Users, apps, deployments, scaling rules
+- **Redis**
+  - Caching
+  - Session storage
+  - Queues & pub/sub
+
+---
+
+## 🏗️ Build System & Deployment
+
+### Builder Types (Railway-inspired)
+
+**1️⃣ Nixpacks (Primary, Default Builder) ⭐**
+
+Auto-detection build system based on Nix for reproducible builds.
+
+- **How it works**: Scans repo for `go.mod`, `package.json`, `requirements.txt`, etc.
+- **Supports**: Go, Node.js, Bun, Python, Ruby, PHP, Rust, Deno, Static sites
+- **Advantages**: No Dockerfile needed, fast builds, reproducible, easy overrides
+- **Default choice**: Used when no other builder is specified
+
+**2️⃣ Dockerfile Builder**
+
+Standard Docker build using your existing Dockerfile.
+
+- **When to use**: Complex builds, custom system dependencies, non-standard runtimes
+- **Control**: Full control over base image, OS packages, multi-stage builds
+- **Tradeoff**: Slower than Nixpacks, more responsibility
+
+**3️⃣ Prebuilt Image Deployment**
+
+Deploy existing container images from Docker Hub, GHCR, or any OCI registry.
+
+- **Use cases**: Workers, infrastructure tools, third-party services, optimized custom images
+- **Process**: No build step - Railway pulls and runs the image directly
+
+**4️⃣ Platform Templates**
+
+Predefined service configurations that wrap around the above builders.
+
+- **Function**: Predefine services, choose builder type (usually Nixpacks), preconfigure variables & databases
+- **Underlying**: Still uses Nixpacks, Dockerfile, or prebuilt images
+
+### Builder Selection Logic
+
+```
+Dockerfile present? → Docker builder
+Else if image specified? → Image deploy  
+Else → Nixpacks (default)
+```
+
+### Build Output
+
+Regardless of builder type, the result is always:
+- Container image
+- Versioned per deployment
+- Immutable
+- Rollback-able
+
+### Stack Mapping
+
+- **Go backend** → Nixpacks (perfect fit)
+- **Vite/React/Bun** → Nixpacks
+- **Rust helpers** → Nixpacks or Dockerfile
+- **Custom system deps** → Dockerfile
+- **Workers/cron** → Prebuilt image or Nixpacks
+
+---
+
+## 🔁 Scaling Model
+
+- Horizontal scaling via container replicas
+- Node-aware scheduling across Proxmox VMs/LXCs
+- Metrics-based auto-scaling:
+  - CPU
+  - Memory
+  - Request rate
+- Stateless application containers
+- Externalized state (DB, cache, storage)
+
+---
+
+## 📦 Deployment Flow
+
+1. Git push / webhook trigger
+2. Backend schedules build
+3. Docker image is built & stored
+4. Scheduler selects optimal nodes
+5. Node agents start containers
+6. Traefik automatically routes traffic
+7. Metrics collected → scaling decisions applied
+
+---
+
+## � Analytics & Monitoring
+
+### Umami Integration
+- **Privacy-focused web analytics** for user insights
+- **Self-hosted analytics dashboard** for application monitoring
+- **Real-time visitor tracking** with geographic and device data
+- **Performance metrics** including bounce rates and session duration
+- **Traffic source analysis** and top page tracking
+- **GDPR compliant** with no personal data collection
+- **Integration points**:
+  - Dashboard analytics overview
+  - Project-specific metrics
+  - Service performance tracking
+  - User behavior analysis
+
+### Built-in Monitoring
+- **Real-time metrics** with custom visualizations
+- **Service health monitoring** with status indicators
+- **Resource usage tracking** (CPU, memory, storage, network)
+- **Geographic service distribution** with interactive globe
+- **Performance graphs** and data visualizations
+- **Build logs integration** with step-by-step progress tracking
+- **Deployment history** with rollback capabilities
+
+---
+
+## �🔐 Networking & Security
+
+- TLS termination via Traefik
+- Internal service networking
+- Agent authentication via tokens / mTLS
+- No direct Docker socket exposure to UI
+
+---
+
+## 🧩 Design Principles
+
+- Infrastructure-first (Proxmox as the cloud)
+- Stateless by default
+- Explicit over magical
+- Horizontal scalability
+- Fail-fast & observable
+- Open-source friendly
+
+---
+
+## 🚀 Long-Term Vision
+
+- Multi-cluster support
+- Cloud bursting (home → cloud nodes)
+- Preview environments per Git branch
+- Resource-based billing (optional)
+- Plugin system for runtimes & buildpacks
+
+---
+
+## 📄 License
+
+MIT / Apache-2.0 (TBD)
+
+---
+
+## 🛠️ Status
+
+Early architecture & design phase.

docs/archive/research/review_output.json

@@ -0,0 +1,118 @@
+{
+  "assessments": {
+    "naming_quality": 82,
+    "error_consistency": 68,
+    "abstraction_fitness": 75,
+    "logic_clarity": 88,
+    "ai_generated_debt": 72,
+    "type_safety": 70,
+    "contract_coherence": 74
+  },
+  "findings": [
+    {
+      "file": "src/lib/api.ts",
+      "dimension": "type_safety",
+      "line": 95,
+      "confidence": "high",
+      "message": "Return type `any` for user object — define a proper User type matching the auth response (e.g., `{ token: string; user: { id: string; email: string; name: string } }`)."
+    },
+    {
+      "file": "src/lib/api.ts",
+      "dimension": "abstraction_fitness",
+      "line": 6,
+      "confidence": "high",
+      "message": "The `api` object (lines 5-67) duplicates token/auth header logic in all 4 methods, yet `apiCall()` (line 70) already implements this pattern — remove the `api` object or refactor it to use `apiCall` internally."
+    },
+    {
+      "file": "src/lib/api.ts",
+      "dimension": "type_safety",
+      "line": 111,
+      "confidence": "high",
+      "message": "`getProfile` returns `apiCall<any>` — should return a typed `User` from @/types."
+    },
+    {
+      "file": "src/lib/api.ts",
+      "dimension": "type_safety",
+      "line": 133,
+      "confidence": "medium",
+      "message": "`pagination: any` in getProjects response — define `PaginationMeta { page: number; limit: number; total: number; pages: number }`."
+    },
+    {
+      "file": "src/pages/Settings.tsx",
+      "dimension": "error_consistency",
+      "line": 80,
+      "confidence": "high",
+      "message": "Catch block only logs error without propagating or setting error state — either rethrow, set an error state, or show user feedback via toast."
+    },
+    {
+      "file": "src/pages/Settings.tsx",
+      "dimension": "error_consistency",
+      "line": 101,
+      "confidence": "high",
+      "message": "Catch block swallows error silently — add toast notification or error state to inform user of fetch failure."
+    },
+    {
+      "file": "src/components/security/SecurityDashboard.tsx",
+      "dimension": "error_consistency",
+      "line": 108,
+      "confidence": "high",
+      "message": "Catch block only `console.error` — the UI shows stale/empty data with no indication of failure. Set an error state or show an error toast."
+    },
+    {
+      "file": "src/components/security/SecurityDashboard.tsx",
+      "dimension": "error_consistency",
+      "line": 132,
+      "confidence": "high",
+      "message": "Catch block swallows scan start failure — user has no feedback that the scan didn't initiate. Add toast or error state."
+    },
+    {
+      "file": "src/hooks/useAuth.tsx",
+      "dimension": "type_safety",
+      "line": 6,
+      "confidence": "high",
+      "message": "`user: any | null` should be typed as `User | null` using the User type from @/types."
+    },
+    {
+      "file": "src/components/git/DeploymentTriggers.tsx",
+      "dimension": "ai_generated_debt",
+      "line": 64,
+      "confidence": "high",
+      "message": "Comment `// TODO: Replace with actual API call` indicates placeholder code — implement real API integration or extract to a proper mock service for development."
+    },
+    {
+      "file": "src/components/git/DeploymentTriggers.tsx",
+      "dimension": "ai_generated_debt",
+      "line": 106,
+      "confidence": "medium",
+      "message": "Another `// TODO: Replace with actual API call` — these TODOs should be tracked in issue tracker, not committed as code comments."
+    },
+    {
+      "file": "src/components/dashboard/ProjectCanvas.tsx",
+      "dimension": "naming_quality",
+      "line": 342,
+      "confidence": "medium",
+      "message": "Function `getActionButton` returns JSX, not just a button — rename to `renderActionButtons` or `getServiceActionButtons` for clarity."
+    },
+    {
+      "file": "src/components/database/DatabaseDetailPanel.tsx",
+      "dimension": "naming_quality",
+      "line": 148,
+      "confidence": "low",
+      "message": "Parameter `_action` is prefixed with underscore to indicate unused, but the action is still destructured — either use it or remove from the parameter entirely if the mutation doesn't need it."
+    },
+    {
+      "file": "src/pages/Scaling.tsx",
+      "dimension": "ai_generated_debt",
+      "line": 49,
+      "confidence": "medium",
+      "message": "Mock API object `scalingApi` with inline mock data (lines 49-167) should be moved to a separate mock/test utilities file for cleaner production code."
+    },
+    {
+      "file": "src/pages/Projects.tsx",
+      "dimension": "logic_clarity",
+      "line": 128,
+      "confidence": "medium",
+      "message": "Type assertion `as ProjectWithStats[]` after `useMemo` — the API returns `Project[]` but stats are expected. Either add stats to the API response type or document the transformation."
+    }
+  ]
+}

docs/archive/research/timeline.md

@@ -0,0 +1,437 @@
+# Containr Development Timeline
+
+## Phase 1: Foundation & Core Infrastructure (Weeks 1-4)
+
+### Week 1: Project Setup & Architecture
+- [x] **Project Documentation**
+  - Complete project.md with React stack
+  - Define architecture principles
+  - Set up development roadmap
+- [x] **Repository Structure**
+  - Initialize monorepo with backend and frontend
+  - Set up Git workflows and CI/CD pipelines
+  - Configure development environment standards
+
+### Week 2: Backend Foundation
+- [x] **Go Backend Setup** ✅ COMPLETED
+  - ✅ Initialize Go module structure with proper dependencies
+  - ✅ Set up basic HTTP server with Gin framework
+  - ✅ Implement middleware for auth, logging, CORS, and request tracking
+- [x] **Database Schema** ✅ COMPLETED
+  - ✅ Design PostgreSQL schema for users, projects, deployments, services, environments
+  - ✅ Implement database migrations with version tracking
+  - ✅ Set up Redis for caching and sessions (structure ready)
+- [x] **Authentication System** ✅ COMPLETED
+  - ✅ Implement JWT-based authentication with secure password hashing
+  - ✅ Create user registration and login endpoints
+  - ✅ Add profile management and token validation
+
+### Week 3: Frontend Foundation 
+- [x] **React + Vite Setup**
+  - Initialize Vite + React + TypeScript project
+  - Configure Tailwind CSS and shadcn/ui
+  - Set up routing with React Router
+- [x] **Basic UI Framework**
+  - Create layout components (Header, Sidebar, Main)
+  - Implement authentication UI (login/register)
+  - Set up state management with Zustand/Redux Toolkit
+- [x] **Dashboard Components Implementation** 
+  - Implement metric cards (Sales, Visitors, Conversion Rate) with interactive time period selectors
+  - Build charts and visualizations (Visitor Channels, User Retention, Weekly Visitors) with real-time data
+  - Create analytics and monitoring components with advanced styling
+  - Add project canvas with service management UI
+  - Implement responsive design with Tailwind CSS
+- [x] **Advanced Dashboard Features** 
+  - Support Analytics Card with ticket tracking and real-time activity
+  - Campaign Data Card with performance metrics, budget utilization, and monthly trends
+  - Product Categories Card with interactive charts and category performance
+  - Enhanced Project Canvas with Railway-inspired service management
+  - Interactive service detail panels with tabs (overview, deployments, variables, metrics)
+  - Environment management (production, preview, development)
+  - Database management as first-class services
+  - Real-time status indicators and performance metrics
+  - Git integration with commit tracking and deployment history
+  - Advanced metric cards with device breakdown, funnel analysis, and sparkline visualizations
+  - Interactive charts with period selection, hover states, and smooth transitions
+  - Cohort retention heatmap with detailed analytics
+  - Weekly visitor trends with dual-line visualizations
+
+### Week 4: Infrastructure Setup
+- [x] **Backend API Foundation** ✅ COMPLETED EARLY
+  - ✅ Complete Go backend with authentication and project management
+  - ✅ RESTful API endpoints for users, projects, and authentication
+  - ✅ Database migrations and seeding system
+  - ✅ JWT-based authentication with secure password hashing
+- [x] **Frontend-Backend Integration** ✅ COMPLETED
+  - ✅ Complete API client with TypeScript interfaces
+  - ✅ React Query integration for data fetching
+  - ✅ Authentication context and hooks
+  - ✅ Login/register pages with form validation
+  - ✅ Protected routes and authentication flow
+- [x] **Service Management API** ✅ COMPLETED
+  - ✅ Complete CRUD operations for services
+  - ✅ Project-based service isolation
+  - ✅ Service types (web, worker, database, cron)
+  - ✅ Environment management (production, preview, development)
+- [x] **Proxmox Integration** ✅ COMPLETED
+  - ✅ Set up Proxmox API client with authentication
+  - ✅ Implement VM/LXC creation and management
+  - ✅ Add node monitoring and resource tracking
+  - ✅ Create infrastructure management UI with real-time statistics
+  - ✅ Implement container lifecycle management (start, stop, delete)
+  - ✅ Add cluster overview and resource usage visualization
+- [x] **Docker Foundation** ✅ COMPLETED
+  - ✅ Set up Docker client integration
+  - ✅ Implement container management framework
+  - ✅ Add service configuration types and deployment structures
+  - ✅ Create Docker registry and networking support structure
+
+---
+
+## Phase 2: Core Platform Features (Weeks 5-8)
+
+### Week 5: User Management & Auth
+- [x] **Authentication System** ✅ COMPLETED
+  - ✅ Implement JWT-based authentication
+  - ✅ Add OAuth providers (GitHub, GitLab) - structure ready
+  - ✅ Create user profile management
+- [x] **Authorization** ✅ COMPLETED
+  - ✅ Role-based access control (RBAC) - structure ready
+  - ✅ Team/organization management - structure ready
+  - ✅ Project permissions system - structure ready
+
+### Week 6: Project Management
+- [x] **Project CRUD** ✅ COMPLETED
+  - ✅ Complete project management interface with full CRUD operations
+  - ✅ Project listing with search and filtering capabilities
+  - ✅ Project creation and editing with modal interfaces
+  - ✅ Project deletion with confirmation dialogs
+  - ✅ Project statistics and activity tracking
+- [x] **Git Integration** ✅ COMPLETED
+  - ✅ Git provider connections (GitHub, GitLab, Bitbucket)
+  - ✅ Repository connection and management interface
+  - ✅ Git provider authentication with access tokens
+  - ✅ Repository browsing and connection workflow
+- [x] **Webhook Management** ✅ COMPLETED
+  - ✅ Webhook creation and configuration interface
+  - ✅ Event-based webhook triggers (push, pull_request, release)
+  - ✅ Webhook secret management and security
+  - ✅ Branch filtering for webhook triggers
+- [x] **Branch-Based Deployment Triggers** ✅ COMPLETED
+  - ✅ Deployment trigger configuration per branch and service
+  - ✅ Environment-based deployment routing (production, preview, development)
+  - ✅ Auto-deployment vs manual deployment options
+  - ✅ Custom build and start command configuration
+
+### Week 7: Build System Integration
+- [x] **Nixpacks Integration** ✅ COMPLETED
+  - ✅ Implement Nixpacks build detection for multiple runtimes (Go, Node.js, Python, Rust, Ruby, PHP, Deno, Bun, Static)
+  - ✅ Create Nixpacks plan generation with automatic runtime detection
+  - ✅ Build optimization and caching strategies
+  - ✅ Environment variable injection and build customization
+- [x] **Dockerfile Support** ✅ COMPLETED
+  - ✅ Custom Dockerfile builds with validation and optimization
+  - ✅ Multi-stage build optimization suggestions
+  - ✅ Dockerfile generation for common runtimes
+  - ✅ Build context management and caching strategies
+
+### Week 8: Deployment Engine
+- [x] **Basic Deployment** ✅ COMPLETED
+  - ✅ Git push to deployment pipeline with build integration
+  - ✅ Build and container creation with multiple builder support
+  - ✅ Service registration and container orchestration
+  - ✅ Deployment engine with scheduling and node management
+  - ✅ Container lifecycle management (create, start, stop, delete)
+- [x] **Deployment History** ✅ COMPLETED
+  - ✅ Track deployment versions with comprehensive metadata
+  - ✅ Rollback capabilities with deployment history tracking
+  - ✅ Deployment logs and status with real-time monitoring
+  - ✅ Deployment statistics and analytics
+  - ✅ Service and user deployment metrics
+
+---
+
+## Phase 3: Orchestration & Scaling (Weeks 9-12)
+
+### Week 9: Node Agent System
+- [x] **Agent Architecture** ✅ COMPLETED
+  - ✅ Design lightweight Go agent architecture with comprehensive type system
+  - ✅ Agent registration and heartbeat system with secure authentication
+  - ✅ Secure communication framework with token-based auth
+- [x] **Container Orchestration** ✅ COMPLETED
+  - ✅ Agent-based container management with full lifecycle support
+  - ✅ Health checks and auto-restart functionality with configurable policies
+  - ✅ Resource monitoring and reporting with real-time metrics
+- [x] **Frontend Integration** ✅ COMPLETED
+  - ✅ Complete Node Agents management page with real-time status
+  - ✅ Agent resource monitoring with CPU, memory, and storage visualization
+  - ✅ Container management interface with start/stop/restart actions
+  - ✅ Agent capabilities and network interface visualization
+
+### Week 10: Scheduling & Load Balancing
+- [x] **Scheduler Implementation** ✅ COMPLETED
+  - ✅ Node selection algorithms (round-robin, least-loaded, best-fit, random)
+  - ✅ Resource-aware scheduling with CPU and memory constraints
+  - ✅ Affinity and anti-affinity rules framework
+- [x] **Advanced Networking** ✅ COMPLETED
+  - ✅ Service discovery integration with internal DNS
+  - ✅ Load balancing strategies (round-robin, least connections, IP hash, random)
+  - ✅ Internal DNS setup with A and SRV records
+  - ✅ Network utilities for IP management and port allocation
+
+### Week 11: Auto-Scaling
+- [x] **Metrics Collection** ✅ COMPLETED
+  - ✅ CPU, memory, network metrics with real-time collection
+  - ✅ Custom application metrics framework
+  - ✅ Performance data aggregation with PostgreSQL storage
+  - ✅ Prometheus export format support
+- [x] **Scaling Engine** ✅ COMPLETED
+  - ✅ Horizontal pod auto-scaling with configurable policies
+  - ✅ Scaling policies and thresholds with cost optimization
+  - ✅ Scale up/down steps and cooldown periods
+  - ✅ Multi-metric scaling (CPU, memory, requests, error rate)
+- [x] **Cost Optimization** ✅ COMPLETED
+  - ✅ Cost-aware scaling with maximum hourly budgets
+  - ✅ Resource efficiency preferences
+  - ✅ Idle timeout configurations
+  - ✅ Scaling impact estimation
+
+### Week 12: High Availability
+- [x] **Fault Tolerance** ✅ COMPLETED
+  - ✅ Multi-node redundancy with automatic failover
+  - ✅ Failover mechanisms with configurable policies
+  - ✅ Disaster recovery procedures with backup nodes
+  - ✅ Health checking system with multiple check types
+- [x] **Monitoring & Alerting** ✅ COMPLETED
+  - ✅ Alert rule engine with configurable conditions
+  - ✅ Multiple notification channels (email, Slack, webhook)
+  - ✅ Alert lifecycle management (firing, resolved)
+  - ✅ Health status monitoring and reporting
+- [x] **High Availability Manager** ✅ COMPLETED
+  - ✅ Centralized HA management with comprehensive API
+  - ✅ Failover policy management per service
+  - ✅ Health check configuration and results
+  - ✅ Alert rule and notifier management
+
+---
+
+## Phase 4: Advanced Features (Weeks 13-16)
+
+### Week 13: Analytics & Observability
+- [x] **Umami Integration** ✅ COMPLETED
+  - ✅ Self-hosted analytics setup with complete UI integration
+  - ✅ Privacy-focused tracking with GDPR compliance
+  - ✅ Real-time visitor analytics with geographic and device data
+  - ✅ Performance metrics including bounce rates and session duration
+  - ✅ Traffic source analysis and top page tracking features
+- [x] **Custom Metrics** ✅ COMPLETED
+  - ✅ Application performance monitoring dashboard
+  - ✅ Business metrics tracking and custom dashboard creation
+  - ✅ Infrastructure metrics (CPU, memory, disk, network)
+  - ✅ Real-time alerts and status monitoring
+  - ✅ Custom KPI tracking with goal completion
+
+### Week 14: Database Services
+- [x] **Managed Databases** ✅ COMPLETED
+  - ✅ PostgreSQL as a service with automated provisioning
+  - ✅ Redis as a service with real-time metrics
+  - ✅ MySQL as a service with performance monitoring
+  - ✅ Database backup and restore functionality
+- [x] **Database Integrations** ✅ COMPLETED
+  - ✅ Connection pooling and optimization
+  - ✅ Migration management with version tracking
+  - ✅ Performance monitoring and metrics collection
+  - ✅ Automated backup scheduling and retention policies
+
+### Week 15: Advanced Build Features
+- [x] **Build Caching** ✅ COMPLETED
+  - ✅ Layer caching optimization for faster builds with intelligent cache key generation
+  - ✅ Remote build cache support with registry integration and authentication
+  - ✅ Parallel build execution with worker pools and optimized scheduling
+  - ✅ Cache statistics and management with cleanup capabilities
+- [x] **Custom Runtimes** ✅ COMPLETED
+  - ✅ Support for custom buildpacks with Cloud Native Buildpacks integration
+  - ✅ Runtime version management with automatic detection and configuration
+  - ✅ Dependency optimization with caching and pre-built layers
+  - ✅ Custom runtime detection for Elixir, Dart, Swift, Kotlin, and other languages
+  - ✅ Template-based Dockerfile generation with health checks and optimization
+
+### Week 16: Preview Environments
+- [x] **Branch Deployments** ✅ COMPLETED
+  - ✅ Automatic preview environments with branch-based creation
+  - ✅ Environment promotion workflows (preview → production/development)
+  - ✅ Preview environment cleanup policies with TTL management
+- [x] **Collaboration Features** ✅ COMPLETED
+  - ✅ Environment sharing and access management
+  - ✅ Preview environment status tracking and monitoring
+  - ✅ Integration with existing deployment triggers
+
+---
+
+## Phase 5: Production Readiness (Weeks 17-20)
+
+### Week 17: Security Hardening ✅ COMPLETED
+- [x] **Security Audit System** ✅ COMPLETED
+  - ✅ Comprehensive security scanning framework with vulnerability detection
+  - ✅ Multiple scan types: dependency, configuration, and comprehensive scanning
+  - ✅ Real-time vulnerability assessment with severity classification
+  - ✅ Security metrics and scoring system with historical tracking
+- [x] **Compliance Management** ✅ COMPLETED
+  - ✅ GDPR compliance framework initialization and assessment
+  - ✅ Compliance control management with automated testing
+  - ✅ Risk assessment and mitigation tracking
+  - ✅ Compliance reporting with detailed findings and recommendations
+- [x] **Data Encryption & Privacy** ✅ COMPLETED
+  - ✅ AES-256 encryption for sensitive data at rest and in transit
+  - ✅ Data anonymization for GDPR compliance with retention policies
+  - ✅ Secure audit logging with encrypted sensitive information
+  - ✅ Data subject access request generation and management
+
+### Week 18: Performance Optimization ✅ COMPLETED
+- [x] **Database Optimization** ✅ COMPLETED
+  - [x] Enhanced database connection pooling with configurable parameters
+  - [x] Added performance monitoring and statistics collection
+  - [x] Implemented query optimization with prepared statements and timeouts
+  - [x] Created comprehensive indexing strategy for common query patterns
+  - [x] Added database views for optimized dashboard queries
+  - [x] Implemented batch operations for reduced database round trips
+- [x] **Frontend Optimization** ✅ COMPLETED
+  - [x] Implemented code splitting and lazy loading utilities
+  - [x] Added React Query optimization with caching strategies
+  - [x] Enhanced component memoization and callback optimization
+  - [x] Configured Vite build optimization with chunk splitting
+  - [x] Added asset optimization and compression settings
+  - [x] Implemented pagination and search optimization
+  - [x] Added performance monitoring and error boundaries
+
+### Week 19: Documentation & Onboarding ✅ COMPLETED
+- [x] **Comprehensive Documentation** ✅ COMPLETED
+  - [x] API documentation with OpenAPI specification
+  - [x] User guides and tutorials (Getting Started, Advanced Configuration)
+  - [x] Developer onboarding guides with complete setup instructions
+- [x] **CLI Tools** ✅ COMPLETED
+  - [x] Command-line interface for management with auth and project commands
+  - [x] Automation scripts for building and installation
+  - [x] Integration with existing tools and Makefile targets
+
+### Week 20: Beta Testing & Launch Preparation 📅 NEXT
+- [ ] **Beta Program**
+  - [ ] Beta user onboarding
+  - [ ] Feedback collection and analysis
+  - [ ] Bug fixes and improvements
+- [ ] **Launch Preparation**
+  - [ ] Production deployment checklist
+  - [ ] Monitoring and alerting setup
+  - [ ] Support documentation and processes
+
+---
+
+## Phase 6: Post-Launch (Ongoing)
+
+### Continuous Improvement
+- [ ] **Feature Development**
+  - User feedback-driven features
+  - Performance improvements
+  - New runtime support
+- [ ] **Community Building**
+  - Open source community engagement
+  - Contribution guidelines
+  - Community support channels
+
+### Advanced Features (Future)
+- [ ] **Multi-Cluster Support**
+  - Cross-cluster deployments
+  - Geographic distribution
+  - Cloud bursting capabilities
+- [ ] **Plugin System**
+  - Custom runtime plugins
+  - Third-party integrations
+  - Marketplace for extensions
+- [ ] **Advanced Analytics**
+  - AI-powered optimization
+  - Predictive scaling
+  - Cost optimization recommendations
+
+---
+
+## Milestones & Deliverables
+
+### MVP (Week 8) ✅ Frontend Dashboard Complete - ENHANCED + Week 6 Project Management Complete
+- [x] **Frontend Dashboard Implementation** ✅ COMPLETED WITH ADVANCED FEATURES
+  - ✅ Complete dashboard UI with enhanced metric cards featuring interactive time period selectors
+  - ✅ Analytics and monitoring components with real-time data visualization
+  - ✅ Project canvas with comprehensive Railway-inspired service management
+  - ✅ Responsive design with modern Tailwind CSS styling and smooth transitions
+  - ✅ Advanced analytics features (Support, Campaigns, Product Categories) with detailed metrics
+  - ✅ Interactive service management with real-time status indicators and performance tracking
+  - ✅ Railway-inspired service detail panels with comprehensive tabs (overview, deployments, variables, metrics)
+  - ✅ Environment management (production, preview, development) with proper isolation
+  - ✅ Database management as first-class services with connection tracking
+  - ✅ Git integration with deployment history, commit tracking, and rollback capabilities
+  - ✅ Performance metrics and monitoring capabilities with visual charts
+  - ✅ Advanced campaign and product category visualizations with interactive elements
+  - ✅ Support analytics with ticket tracking, channel breakdown, and real-time activity feeds
+  - ✅ Enhanced metric cards with device breakdown, conversion funnels, and sparkline charts
+  - ✅ Interactive charts including visitor channels, user retention heatmaps, and weekly trends
+  - ✅ Cohort analysis with detailed retention matrices and time-based comparisons
+  - ✅ Modern UI components with hover states, loading animations, and micro-interactions
+- [x] **Project Management System** ✅ COMPLETED
+  - ✅ Full CRUD operations for projects with modern UI
+  - ✅ Project search, filtering, and pagination
+  - ✅ Project statistics and activity tracking
+  - ✅ Modal-based project creation and editing
+  - ✅ Integration with service management
+- [x] **Git Integration Platform** ✅ COMPLETED
+  - ✅ Multi-provider Git integration (GitHub, GitLab, Bitbucket)
+  - ✅ Secure authentication with access token management
+  - ✅ Repository connection and browsing interface
+  - ✅ Webhook management with event-based triggers
+  - ✅ Branch-based deployment triggers with environment routing
+  - ✅ Auto-deployment configuration and manual approval options
+  - ✅ Custom build and start command configuration per trigger
+- Basic user authentication
+- Simple project management
+- Git-based deployments
+- Basic container orchestration
+
+### Beta (Week 16)
+- Full feature set
+- Advanced scaling capabilities
+- Analytics and monitoring
+- Preview environments
+
+### Production (Week 20)
+- Security-hardened platform
+- Performance optimized
+- Comprehensive documentation
+- Production-ready monitoring
+
+---
+
+## Risk Assessment & Mitigation
+
+### Technical Risks
+- **Proxmox API limitations**: Build fallback mechanisms and manual provisioning options
+- **Docker orchestration complexity**: Start with simple orchestration, evolve to more complex patterns
+- **Performance at scale**: Implement early performance testing and optimization
+
+### Project Risks
+- **Scope creep**: Maintain strict MVP focus for initial release
+- **Technical debt**: Regular refactoring and code review practices
+- **Team coordination**: Clear documentation and communication protocols
+
+---
+
+## Success Metrics
+
+### Technical Metrics
+- Deployment success rate > 99%
+- Platform uptime > 99.9%
+- Average deployment time < 5 minutes
+- Auto-scaling response time < 2 minutes
+
+### Business Metrics
+- User adoption rate
+- Customer satisfaction score
+- Platform utilization metrics
+- Community engagement levels