overhaul

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.