Gitea

# MISSION: Scaffold "Gitea" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Gitea**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Gitea
- **What It Does**: Gitea is a self-hosted, all-in-one software development platform that bundles Git hosting, code review, issue tracking, a package registry and GitHub Actions-compatible CI/CD into a single Go binary.
- **Domain & Category**: Lightweight Self-Hosted Git Service
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: One Go process fronted by XORM abstracts four relational databases and pluggable search/storage backends, so the same codebase scales from a single SQLite file on a Raspberry Pi to a MySQL- or PostgreSQL-backed team instance.
- **Live Website Reference**: https://about.gitea.com
- **Source Repository**: https://github.com/go-gitea/gitea
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Go, TypeScript, Vue, XORM, SQLite, PostgreSQL, MySQL, Redis, Bleve, Docker
- **Primary Language(s)**: Go, TypeScript
- **License of the reference repo**: MIT
- **Frontend**: Vue — Vue 3.5 components inside the server-rendered templates, wired up via @vitejs/plugin-vue.; Vite — Bundles web_src/js and web_src/css; referenced as a frontend config in the Makefile.; Tailwind CSS — Utility CSS (tailwind.config.ts) alongside the legacy Less stylesheets.; CodeMirror — In-browser code, Markdown and JSON editors (@codemirror/lang-markdown, -json, autocomplete, lint).; Chart.js — Repository activity and contribution graphs via chart.js and chartjs-plugin-zoom.
- **Backend & APIs**: Go — The server, CLI (cmd/) and background workers are one Go module, gitea.dev, go 1.27.; XORM — ORM for every supported database, used throughout models/ (xorm.io/xorm, xorm.io/builder).; Gitea Actions — Built-in CI runner compatible with GitHub Actions workflow syntax.; Chi — HTTP routing for the web and API routers (go-chi/chi/v5, go-chi/cors).
- **Data & persistence**: SQLite — Default single-file database for small instances (mattn/go-sqlite3 and modernc.org/sqlite).; MySQL — Supported production database via go-sql-driver/mysql; covered by its own integration-test matrix.; PostgreSQL — Supported production database via lib/pq.; Redis — Cache, queue and session backend (redis/go-redis/v9, modules/cache, modules/queue, modules/nosql).; Bleve — Embedded full-text indexer for code and issue search, the default when no external engine is set (blevesearch/bleve/v2).; MinIO — S3-compatible object storage backend for LFS objects, avatars and attachments (minio-go/v7).
- **Infrastructure & deploy**: Docker — Three-stage build (frontend, backend, alpine runtime); s6 supervises sshd and the web process.; GitHub Actions — Gitea's own CI: DB test matrix, Playwright e2e, Docker dry-run, nightly Snapcraft and release workflows.; Nix — flake.nix provides a reproducible Nix build/dev shell.
- **Tooling, testing & ops**: Playwright — Browser end-to-end tests (@playwright/test, tests/e2e, playwright.config.ts).; ESLint — TypeScript/Vue linting via eslint.config.ts with @stylistic/eslint-plugin.; Stylelint — CSS/Less linting via @stylistic/stylelint-plugin.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/go-gitea/gitea @ 4892a55)
1. **One ORM abstracts four relational databases**: go.mod pulls in drivers for SQLite (mattn/go-sqlite3, modernc.org/sqlite), MySQL (go-sql-driver/mysql), PostgreSQL (lib/pq) and MSSQL (microsoft/go-mssqldb), all accessed through xorm.io/xorm in models/db. tests/mysql.ini.tmpl, tests/pgsql.ini.tmpl, tests/mssql.ini.tmpl and tests/sqlite.ini.tmpl back a dedicated pull-db-tests.yml CI matrix so no backend regresses silently.
2. **CI/CD is reimplemented in-repo as Gitea Actions**: modules/actions, services/actions and routers/api handle a GitHub Actions-compatible runner and workflow format, so a self-hosted instance gets CI/CD without wiring up Jenkins, Drone or an external runner — the tradeoff is Gitea now maintains its own workflow-syntax compatibility layer.
3. **Search and object storage are both pluggable**: modules/indexer and services/indexer default to an embedded Bleve index (blevesearch/bleve/v2) but can delegate to Meilisearch (meilisearch/meilisearch-go) for larger instances; modules/storage does the same for file storage, defaulting to local disk but supporting MinIO/S3 (minio-go/v7) for LFS objects, avatars and attachments.
4. **Schema migrations are versioned by release, not squashed**: modelmigration/v1_6 through v1_27 (plus v28) keep every historical schema-migration step as its own package rather than collapsing history, so an instance can upgrade from a very old release without a separate migration tool.
5. **The container runs an init system, not a single process**: The final Docker stage installs openssh and s6, and its CMD is s6-svscan rather than the gitea binary directly, because the container must run both the SSH server for git+ssh access and the web/API server as supervised sibling processes.
6. **Frontend build tooling migrated to Vite while legacy jQuery remains**: package.json still lists jquery (4.0.0) and Less alongside Vue 3, Vite and Tailwind CSS; the Makefile FRONTEND_SOURCES variable finds files under both web_src/js and web_src/css, reflecting an incremental migration rather than a rewrite.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (SQLite, MySQL, PostgreSQL, Redis, Bleve, MinIO): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.