Architecture Design

Overall Architecture

┌─────────────────────────────────────────────────────┐
│                Browser / Git Client                  │
└──────────┬──────────────────────┬───────────────────┘
           │ HTTP (3001)          │ HTTP/SSH (8081/2022)
           ▼                      ▼
┌──────────────────┐    ┌──────────────────────────────┐
│  web (Next.js)   │    │       server (Go + Fiber)     │
│  ┌────────────┐  │    │  ┌──────────┐  ┌───────────┐  │
│  │ SSR/CSR    │──┼────┼─▶│ Router   │─▶│ Handler   │  │
│  │ Chakra UI  │  │    │  │ Middleware│  │ Service   │  │
│  └────────────┘  │    │  └──────────┘  └─────┬─────┘  │
└──────────────────┘    │                      │        │
                        │  ┌───────────────────▼──────┐ │
                        │  │  Repository (GORM)       │ │
                        │  │  ┌─────────────────────┐ │ │
                        │  │  │ SQLite/MySQL/PG     │ │ │
                        │  │  └─────────────────────┘ │ │
                        │  └───────────────────────────┘ │
                        │  ┌───────────────────────────┐ │
                        │  │  Git Service (go-git)     │ │
                        │  │  ┌─────────────────────┐  │ │
                        │  │  │  repositories/      │  │ │
                        │  │  │  (bare git repos)   │  │ │
                        │  │  └─────────────────────┘  │ │
                        │  └───────────────────────────┘ │
                        └──────────────────────────────┘

Backend Layering

Layer	Responsibility	Directory
Router	Route registration, middleware chain	internal/router/
Handler	HTTP request handling, parameter validation, response serialization	internal/handler/
Service	Business logic, transaction orchestration	internal/service/
Repository	Data access, GORM operations	internal/repository/
Model	Data model definitions	internal/model/
Middleware	Authentication, CORS, rate limiting, logging	internal/middleware/
Git	Git operation encapsulation (with input validation, repository locks)	internal/git/
Container	Dependency injection container	internal/container/

Git Security Layer

The internal/git/ package provides all Git operations and includes built-in security mechanisms:

File	Responsibility
validation.go	Input validation tools (IsValidRefName, ValidateRepoPath, IsValidCommitHash)
lock.go	Repository-level concurrency locks (GetRepoLock)
branches.go	Branch operations (with input validation and locks)
tags.go	Tag operations (with input validation and locks)
files.go	File operations (with path validation and locks)
commits.go	Commit queries
diff.go	Diff comparison

Dependency Injection

All services are managed uniformly through container.Container, initialized at startup, and handlers obtain service instances through the container.

Database Migration

Startup sequence:
InitGORMDB → AutoMigrate (create tables) → RunMigrations (data backfill)

• AutoMigrate: GORM automatic table/column creation (idempotent)
• RunMigrations: Versioned SQL migration (internal/database/migrations/*.up.sql)

Frontend Architecture

Next.js App Router

web/src/
├── app/                    # Page routes
│   ├── [owner]/[repo]/    # Repository-related pages
│   ├── projects/[slug]/   # Project management pages
│   ├── admin/             # Admin dashboard
│   └── settings/          # User settings
├── components/             # Shared components
├── contexts/              # React Context (authentication, WebSocket, i18n)
├── lib/                   # Utility functions, API client
└── api/                   # API request encapsulation

API Client

ApiClient in lib/api.ts uniformly handles:

• Authentication token (localStorage + cookie)
• Request/response interception
• 401 automatic redirect to login
• API base URL dynamic adaptation (browser hostname)

Internationalization

Uses I18nContext + JSON locale files (src/locales/en.json / zh.json).