# 🌌 COSMOS Architecture & Technical Specifications Cosmos is an open-source, self-hosted cloud platform engineered to transform ordinary consumer hardware or retired office computers into an enterprise-class personal workstation and private cloud. --- ## πŸ—οΈ High-Level Topology ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Client / Web β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ HTTPS / SSL (:443) β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Nginx Reverse Proxy β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ HTTP / β”‚ HTTP / β”‚ HTTP / β”‚ Portals β”‚ Gitea β”‚ MinIO β”‚ (:8080) β”‚ (:3000) β”‚ (:9000) β”‚ β–Ό β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Cosmos Core β”‚ β”‚ Gitea Forge β”‚ β”‚ MinIO S3 β”‚ β”‚ (Go App) β”‚ β”‚ (Git Engine)β”‚ β”‚(Object Storeβ”‚ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ CQL (:9042) β”‚ Local Storage β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ ScyllaDB β”‚ β”‚ Local Disks β”‚ β”‚ (NoSQL Store) β”‚ β”‚(NVMe / HDD) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` --- ## 🧩 Core Architectural Components ### 1. Unified Identity & Application Core (`portals-go`) * **Language:** Go (Golang) 1.22+ * **Serving:** Native `net/http` server with embedded HTML/CSS templates via `embed.FS`. * **Single Sign-On (SSO):** A centralized identity provider managing accounts across S3 Storage and Git Source Control. * **Security Model:** * Passwords hashed with `golang.org/x/crypto/bcrypt`. * Temporary registration passwords stored in transient, self-expiring memory structures (`sync.Map`) only during automated provisioningβ€”never stored plain-text in database storage. * Session identification using cryptographically random UUIDs stored in HTTP-only cookies and ScyllaDB secondary index lookups. ### 2. Distributed Persistence Layer (`ScyllaDB`) * **Database Engine:** ScyllaDB 5.x / Apache Cassandra compatibility mode. * **Protocol:** CQL native binary protocol over port `9042`. * **Keyspace Model:** * `cosmos.users`: Master user directory holding bcrypt hashes, S3 credentials, display metadata, and active session tokens. * `cosmos.pending`: Ephemeral registration tokens and OTP codes. * `cosmos.password_reset_tokens`: Time-expiring password reset tokens. * `cosmos.buckets`: User bucket metadata, ownership tracking, and friendly aliases. * `cosmos.bucket_domains`: Vanity domain and CNAME mapping for public bucket serving. * `cosmos.quota_requests`: Administrative quota elevation queue. * `cosmos.s3_analytics` & `cosmos.s3_analytics_hourly`: Telemetry tracking counters. ### 3. High-Performance Object Storage (`MinIO S3`) * **Engine:** MinIO S3-compatible object storage daemon. * **Automated Tenant Provisioning:** * Upon account activation, the Cosmos core automatically invokes the MinIO Client (`mc`) to provision dedicated IAM users. * Each user is constrained by an isolated AWS IAM policy restricting `s3:*` actions solely to their assigned bucket ARN (`arn:aws:s3:::cosmos-/*`). * Automatic object versioning is enabled by default to prevent accidental data loss. * Storage quotas (default 10GB, expandable via admin approval) are enforced at the bucket level. ### 4. Git Engine & Source Control (`Gitea`) * **Engine:** Gitea self-hosted Git service running on port `3000`. * **Authentication Sync:** * Cosmos manages registration and credential synchronization via CLI/API hooks (`gitea admin user create`, `gitea admin user change-password`). * Auto-healing authentication logic: if credentials fall out of sync during login, Cosmos automatically re-synchronizes the bcrypt hash with Gitea's internal database and retries transparently. ### 5. Real-Time Telemetry & Observability * **In-Memory Accumulator:** High-throughput `atomic.Int64` counters for request counts, bytes transferred, and status code categories (2xx, 4xx, 5xx). * **Periodic Flushing:** Background goroutine flushes aggregated metrics to ScyllaDB hourly tables (`cosmos.s3_analytics_hourly`). * **Visual Telemetry:** Interactive 3D rotating orthographic globe rendered on HTML5 Canvas using vector latitude/longitude projections, simulating real-time global traffic node activity. --- ## πŸ”’ Security Hardening 1. **Least-Privilege Storage Isolation:** Users can never view or manipulate storage belonging to other accounts. Every S3 access request is validated against ScyllaDB session keys and verified via MinIO IAM policies. 2. **Environment Variable Decoupling:** All sensitive endpoints, administrative emails, domain names, and database credentials are fully externalized via `.env` configurations. 3. **Transient Memory Buffering:** Credentials required for downstream provisioning (such as Gitea account creation) exist in memory for a maximum 15-minute window before automatic garbage collection.