Architecture Overview

Understanding Gitea’s architecture and codebase structure

Overview

Gitea is a full-stack web application built with Go on the backend and Vue.js on the frontend. It follows a modular, layered architecture that separates concerns and enables maintainability.

Technology Stack

Backend

• Language: Go 1.26+
• Web Framework: Chi router
• ORM: XORM
• Template Engine: Go templates

Frontend

• Framework: Vue.js 3.5+
• Build Tool: Webpack 5
• Language: TypeScript
• Styling: CSS with Tailwind

Database

• PostgreSQL (recommended)
• MySQL / MariaDB
• SQLite3
• MSSQL

Storage

• Local filesystem
• S3-compatible (MinIO, AWS S3)
• Azure Blob Storage

Directory Structure

gitea/
├── cmd/                  # Command-line interface
│   ├── web.go           # Web server command
│   ├── admin.go         # Admin commands
│   └── ...
├── models/              # Database models and schemas
│   ├── user/            # User models
│   ├── repo/            # Repository models
│   ├── issues/          # Issue/PR models
│   └── ...
├── modules/             # Shared utility modules
│   ├── git/             # Git operations
│   ├── auth/            # Authentication
│   ├── setting/         # Configuration
│   └── ...
├── routers/             # HTTP request routing
│   ├── web/             # Web UI routes
│   ├── api/             # API routes
│   └── ...
├── services/            # Business logic layer
│   ├── repository/      # Repository services
│   ├── user/            # User services
│   ├── issue/           # Issue services
│   └── ...
├── templates/           # HTML templates
│   ├── repo/            # Repository pages
│   ├── user/            # User pages
│   └── ...
├── web_src/             # Frontend source code
│   ├── js/              # JavaScript/TypeScript
│   ├── css/             # Stylesheets
│   └── ...
├── public/              # Static assets (compiled)
├── options/             # Configuration templates
└── tests/               # Test suites

Layered Architecture

Gitea follows a clean architecture with clear separation of concerns:

Layer Responsibilities

1. Routers Layer

   Location: routers/web/, routers/api/

   • Handle HTTP requests/responses
   • Parse request parameters
   • Validate input
   • Call service layer
   • Render responses (HTML or JSON)

   // Example router handler
   func CreateRepository(ctx *context.Context) {
       form := web.GetForm(ctx).(*forms.CreateRepoForm)
       repo, err := repo_service.CreateRepository(ctx, ctx.Doer, form.ToCreateRepoOption())
       if err != nil {
           ctx.Error(http.StatusInternalServerError)
           return
       }
       ctx.JSON(http.StatusCreated, convert.ToRepo(repo, permission.AccessModeOwner))
   }
   
2. Services Layer

   Location: services/

   • Implement business logic
   • Orchestrate multiple operations
   • Handle transactions
   • Emit notifications/webhooks

   // Example service function
   func CreateRepository(ctx context.Context, doer *user_model.User, opts CreateRepoOptions) (*repo_model.Repository, error) {
       // Validate
       // Create repository record
       // Initialize git repository
       // Set up default branch
       // Trigger webhooks
       return repo, nil
   }
   
3. Models Layer

   Location: models/

   • Define data structures
   • Database operations (CRUD)
   • Query builders
   • Migrations

   // Example model
   type Repository struct {
       ID          int64
       OwnerID     int64
       Name        string
       Description string
       IsPrivate   bool
       CreatedUnix timeutil.TimeStamp
   }
   
   func GetRepositoryByID(ctx context.Context, id int64) (*Repository, error) {
       repo := new(Repository)
       has, err := db.GetEngine(ctx).ID(id).Get(repo)
       if !has {
           return nil, ErrRepoNotExist{ID: id}
       }
       return repo, err
   }
   
4. Modules Layer

   Location: modules/

   • Utility functions
   • External integrations
   • Git operations
   • Authentication providers

Key Components

Git Integration

Gitea interacts with Git repositories through:

• Native Git: Executes git commands via modules/git/
• Git LFS: Large file storage support
• Git Hooks: Server-side and client-side hooks

Authentication System

Multiple authentication backends:

// modules/auth/
- LDAP (Bind DN and Simple Auth)
- OAuth2 (GitHub, GitLab, Google, etc.)
- SMTP
- PAM
- SSPI (Windows)

Database Abstraction

XORM provides database-agnostic queries:

// Works across PostgreSQL, MySQL, SQLite, MSSQL
repos, err := db.Find(ctx, FindRepoOptions{
    OwnerID: userID,
    Private: false,
    Page:    1,
    PageSize: 20,
})

Queue System

Asynchronous task processing:

// Background jobs
- Email notifications
- Webhook deliveries
- Repository mirroring
- Git garbage collection

Request Flow

Web Request Example

1. User visits /user/repo/issues/new
   ↓
2. Chi router matches route → routers/web/repo/issue.go
   ↓
3. Handler validates permissions (middleware)
   ↓
4. Handler calls services/issue/Create()
   ↓
5. Service creates issue in database (models/issues/)
   ↓
6. Service triggers notifications and webhooks
   ↓
7. Handler renders HTML template (templates/repo/issue/new.tmpl)
   ↓
8. Response sent to user

API Request Example

1. POST /api/v1/repos/:owner/:repo/issues
   ↓
2. API router → routers/api/v1/repo/issue.go
   ↓
3. Authenticate token (middleware)
   ↓
4. Parse JSON request body
   ↓
5. Call services/issue/Create()
   ↓
6. Return JSON response

Database Schema

Core database tables:

-- Users and authentication
user, email_address, access_token, oauth2_application

-- Repositories
repository, release, branch, protected_branch

-- Collaboration
issue, pull_request, comment, review, milestone, label

-- Organizations
org_user, team, team_user, team_repo

-- Actions (CI/CD)
action_run, action_run_job, action_runner

-- Packages
package, package_version, package_file

Middleware

Request middleware pipeline:

// Common middleware
- Context initialization
- Session management
- CSRF protection
- Authentication
- Permission checks
- Rate limiting
- Logging

See Also

Database Layer

Deep dive into database architecture

Frontend

Frontend architecture and build system

Contributing

Learn how to contribute

Building

Build Gitea from source