6.3 KiB
6.3 KiB
🌌 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/httpserver with embedded HTML/CSS templates viaembed.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.
- Passwords hashed with
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-<id>/*). - 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.
- Upon account activation, the Cosmos core automatically invokes the MinIO Client (
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.
- Cosmos manages registration and credential synchronization via CLI/API hooks (
5. Real-Time Telemetry & Observability
- In-Memory Accumulator: High-throughput
atomic.Int64counters 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
- 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.
- Environment Variable Decoupling:
All sensitive endpoints, administrative emails, domain names, and database credentials are fully externalized via
.envconfigurations. - 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.