Architecture

This page explains how Stasis is structured internally. You don't need to understand this to use Stasis, but it's helpful if you want to contribute or troubleshoot.

High-Level Overview

Stasis has four main components:

┌─────────────────────────────────────────────────────────┐
│                        NGINX                            │
│                   (Reverse Proxy)                       │
└─────────────────┬───────────────────┬───────────────────┘
                  │                   │
                  ▼                   ▼
        ┌─────────────────┐  ┌─────────────────┐
        │   API Server    │  │   Web Frontend  │
        │      (Go)       │  │    (Next.js)    │
        └────────┬────────┘  └─────────────────┘
                 │
                 ▼
        ┌─────────────────┐
        │   PostgreSQL    │
        │   (Database)    │
        └─────────────────┘

NGINX

The entry point. It routes requests:

/api/* → API Server
/ → Web Frontend
Git Smart HTTP requests → API Server

API Server (Go)

The backend. Handles:

Authentication (OIDC)
Repository management
Git protocol (SSH and HTTP)
User profiles
Tokens and SSH keys

Web Frontend (Next.js)

The UI you see in your browser. It communicates with the API server to display repositories, commits, and settings.

PostgreSQL

Stores all persistent data:

User accounts and profiles
Repository metadata
SSH keys and tokens
CI/CD job records

Directory Structure

stasis/
├── cmd/
│   └── server/           # Main entry point
├── internal/
│   ├── application/      # Business logic
│   │   ├── dto/          # Data transfer objects
│   │   └── service/      # Service implementations
│   ├── config/           # Configuration loading
│   ├── domain/           # Domain models
│   │   ├── models/       # Data structures
│   │   └── repository/   # Repository interfaces
│   ├── infrastructure/   # External integrations
│   │   ├── git/          # Git operations
│   │   └── repository/   # Database implementations
│   └── transport/        # HTTP and SSH handlers
│       ├── http/         # REST API handlers
│       └── ssh/          # SSH server
├── web/                  # Next.js frontend
│   ├── app/              # Pages and routes
│   ├── components/       # React components
│   └── lib/              # Utilities and API client
├── configs/              # Configuration files
└── deploy/               # Deployment configs (nginx, etc.)