Reference
Architecture
SkyPort architecture and design overview
Architecture Overview
SkyPort is a modular, self-hosted infrastructure platform designed with separation of concerns and scalability in mind.
System Components
1. CLI (Command-Line Interface)
The lightweight CLI tool for automation and scripting.
Technology: Go
Features:
- Local and remote server management
- Docker, PM2, and VPS commands
- Marketplace integration
- Authentication and credentials management
Location: cli/
2. Backend Server (WebUI Server)
The core API server that manages infrastructure.
Technology: Go
Features:
- REST API endpoints
- WebSocket for real-time updates
- Docker integration
- PM2 process management
- VPS/SSH access
- Marketplace registry
Location: backend/
3. Frontend Dashboard
The web-based user interface.
Technology: React + Vite + TailwindCSS
Features:
- Real-time metrics dashboard
- Container management UI
- Process management UI
- Terminal access
- Application marketplace
Location: frontend/
4. Documentation Site
Professional documentation and guides.
Technology: Nuxt + Docus
Location: docs/
Architecture Diagram
┌─────────────────────────────────────────────────────────────┐
│ User Interfaces │
├──────────────────────┬──────────────────┬──────────────────┤
│ Web Dashboard │ CLI (skyport) │ TUI (Terminal) │
│ (React Frontend) │ (Go Binary) │ (Bubble Tea) │
└──────────────────────┴──────────────────┴──────────────────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌───────────▼─────────┐
│ API Server │
│ (Go Backend) │
│ :8080/api │
└───────────┬─────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼────┐ ┌──────▼────┐
│ Docker │ │ PM2 │ │ VPS │
│ Engine │ │ Processes │ │ Services │
└──────────────┘ └───────────┘ └──────────┘
│ │ │
┌───────▼──────┐ ┌──────▼────┐ ┌──────▼────┐
│ Containers │ │ Apps │ │ SSH │
│ & Images │ │ (Node.js) │ │ Access │
└──────────────┘ └───────────┘ └──────────┘
Data Flow
CLI Command Flow
User Command (CLI)
↓
Local Config (~/.skyport/config.yaml)
↓
Authentication (Token/Credentials)
↓
API Server (:8080/api)
↓
Docker/PM2/VPS Handler
↓
Operation Execution
↓
Result → Output (JSON/Table)
Dashboard Real-Time Flow
Web Browser
↓
WebSocket Connection (:8080/ws)
↓
API Server (persistent connection)
↓
Metrics Collection
↓
Real-Time Updates (every 2-5 seconds)
↓
Frontend Dashboard Update
Directory Structure
SkyPort/
├── cli/ # CLI application
│ ├── cmd/ # CLI commands
│ ├── internal/ # CLI internals
│ │ ├── api/ # API client
│ │ ├── config/ # Configuration
│ │ ├── detector/ # Project detection
│ │ ├── docker/ # Docker integration
│ │ ├── pm2/ # PM2 integration
│ │ ├── ssh/ # SSH/VPS support
│ │ ├── ui/ # UI formatting
│ │ └── tui/ # Terminal UI
│ └── main.go # Entry point
│
├── backend/ # Backend server
│ ├── cmd/ # Server entry point
│ ├── internal/ # Backend modules
│ │ ├── api/ # REST API
│ │ ├── auth/ # Authentication
│ │ ├── docker/ # Docker API
│ │ ├── pm2/ # PM2 management
│ │ ├── vps/ # VPS management
│ │ ├── database/ # Database layer
│ │ ├── models/ # Data models
│ │ ├── websocket/ # WebSocket
│ │ └── metrics/ # Monitoring
│ └── main.go # Entry point
│
├── frontend/ # React dashboard
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── pages/ # Page components
│ │ ├── features/ # Feature modules
│ │ ├── services/ # API services
│ │ └── stores/ # State management
│ └── vite.config.ts # Build config
│
└── docs/ # Documentation
├── content/ # Markdown docs
├── components/ # Doc components
└── nuxt.config.ts # Config
Component Communication
Protocols
| Component | Protocol | Port | Purpose |
|---|---|---|---|
| CLI → API | REST/HTTP | 8080 | Commands |
| Dashboard → API | REST/HTTP + WS | 8080 | UI updates |
| API → Docker | Socket | /var/run/docker.sock | Container management |
| API → PM2 | IPC | - | Process management |
| CLI/API → VPS | SSH | 22 | Remote access |
API Endpoints
GET /api/status # Server status
GET /api/metrics # System metrics
GET /api/docker/ps # List containers
GET /api/docker/images # List images
POST /api/docker/run # Run container
GET /api/pm2/list # List processes
POST /api/pm2/start # Start process
GET /api/vps/servers # List VPS servers
POST /api/auth/login # Authenticate
WS /ws # WebSocket (real-time)
Configuration Management
File Locations
| Component | Config Location | Format |
|---|---|---|
| CLI | ~/.skyport/config.yaml | YAML |
| Server | ~/.skyport/config.yaml | YAML |
| Docker | /etc/docker/daemon.json | JSON |
| PM2 | ecosystem.config.js | JavaScript |
Configuration Hierarchy
1. Environment Variables (highest priority)
↓
2. Command-line Flags
↓
3. Configuration Files
↓
4. Built-in Defaults (lowest priority)
Security Architecture
Authentication
User Credentials
↓
Login Request
↓
Token Generation (JWT)
↓
Token Storage (secure, encrypted)
↓
Token Validation on Requests
↓
Access Granted/Denied
Authorization
- Role-based access control (RBAC)
- Server-level permissions
- Resource-level access control
Data Protection
- Credentials stored in local keyring
- API tokens cached locally
- SSH keys managed securely
- HTTPS/TLS for all remote communication
Scalability Design
Horizontal Scaling
- Stateless API servers
- Shared configuration storage
- Load balancing support
- Multi-server orchestration
Vertical Scaling
- Memory-efficient Go binaries
- Optimized Docker socket access
- Efficient WebSocket connections
- Resource limit configuration
Extension Points
Adding New Services
- Create handler in
backend/internal/ - Define API endpoints
- Add CLI commands in
cli/cmd/ - Update documentation
Custom Integrations
- REST API for third-party tools
- WebSocket for real-time data
- CLI hooks for automation
Dependencies
Core Dependencies
Go (1.20+):
- Docker SDK
- SSH client (golang.org/x/crypto)
- Charm Bubble Tea (TUI)
- Lip Gloss (formatting)
Frontend (Node.js 18+):
- React 18
- TypeScript
- Vite
- TailwindCSS
External Services
- Docker daemon (via socket)
- PM2 (via API)
- SSH servers (for VPS)
Deployment Topology
Single Server
┌─────────────────────┐
│ VPS / Server │
│ ┌─────────────────┐ │
│ │ SkyPort │ │
│ │ ├─ CLI │ │
│ │ ├─ API Server │ │
│ │ └─ Dashboard │ │
│ └─────────────────┘ │
│ ┌─────────────────┐ │
│ │ Docker │ │
│ │ PM2 │ │
│ │ Services │ │
│ └─────────────────┘ │
└─────────────────────┘
High Availability
┌──────────────────────────────────────────┐
│ Load Balancer │
│ (HAProxy / Nginx / F5) │
└──┬───────────────────────────────┬───────┘
│ │
┌──▼──────────────┐ ┌──────▼────────┐
│ SkyPort #1 │ │ SkyPort #2 │
│ Port 8080 │ │ Port 8080 │
│ + Docker │ │ + Docker │
│ + PM2 │ │ + PM2 │
└─────────────────┘ └───────────────┘
│ │
└──────────────┬────────────────┘
│
┌─────────▼────────┐
│ Shared Storage │
│ (NFS/S3/etc) │
└──────────────────┘
Related: CLI Reference | API Documentation