gitea/.codex-project-map.md

# Gitea Project Map for Codex

This file is the persistent implementation map for fast project orientation.

Use it after `./.codex-context.md` when a task needs architecture, flow, or extension-point context.

## 1. Fast Entry Points Index

- auth -> `routers/web/auth/`, `templates/user/auth/`, `services/auth/`
- installer -> `routers/install/`, `templates/install.tmpl`, `options/locale/`
- user settings UI -> `routers/web/user/setting/`, `templates/user/settings/`, `web_src/js/features/`, `web_src/css/modules/`
- sticky menus / persistent layout UI -> `templates/*/navbar*.tmpl`, `web_src/css/modules/menu.css`, `web_src/css/modules/flexcontainer.css`, `web_src/js/features/common-page.ts`
- repo settings / actions UI -> `routers/web/repo/`, `templates/repo/`, `templates/repo/settings/`
- admin UI -> `routers/web/admin/`, `templates/admin/`
- mail / notifications -> `services/mailer/`, `templates/mail/`, `routers/web/admin/`, `routers/web/auth/`
- custom release maintenance and repo-sync helpers -> `./.maintain-custom-release.sh`, `./.update-gitea.sh`, `./.import-upstream-cherry-pick.sh`, `./.codex-script-notes.md`

## 2. Repository Map

- Executable entry point: `main.go`
- CLI lifecycle and command startup: `cmd/`
- Installed-instance initialization and route-tree mounting: `routers/init.go`
- Web SSR routes: `routers/web/`
- API routes: `routers/api/`
- Request context, session, template data, response helpers: `services/context/`
- Business logic: `services/`
- Persistence and domain models: `models/`
- Cross-cutting infrastructure: `modules/`
- Server-side templates: `templates/`
- Browser-side frontend: `web_src/`

## 3. Bootstrap and Request Flow

### 2.1 Application Bootstrap

1. `main.go`
- Sets `setting.AppVer`, `setting.AppBuiltWith`, and `setting.AppStartTime`.
- Starts the CLI app through `cmd.NewMainApp(...)` and `cmd.RunMainApp(...)`.

2. `cmd/web.go`
- `newWebCommand()` defines the `web` command.
- `runWeb(...)` prepares graceful shutdown.
- `serveInstalled(...)` calls `routers.InitWebInstalled(...)` and then `routers.NormalRoutes()`.

3. `routers/init.go`
- `InitWebInstalled(...)` initializes Git, settings, storage, cache, DB, models, auth, indexers, webhooks, SSH, Actions, and cron.
- `NormalRoutes()` mounts:
  - `/` -> `routers/web.Routes()`
  - `/api/v1` -> public API
  - `/api/internal` -> private API
  - optional package and Actions API areas when enabled

### 2.2 Web Request Pipeline

1. `routers/web/web.go:Routes()`
- Builds the main web router.
- Exposes static assets, avatars, `robots.txt`, `metrics`, and `healthz`.

2. Core middleware
- `common.MustInitSessioner()` prepares the session.
- `context.Contexter()` builds the web context and template data.
- `newWebAuthMiddleware()` resolves optional or required authentication.

3. `services/context/`
- `NewBaseContext(...)` creates the base request context.
- `NewWebContext(...)` attaches `Doer`, `Repo`, `Org`, `Session`, `Flash`, and `PageData`.
- `Contexter()` injects global template and page data such as:
  - `Link`
  - `PageData`
  - flash cookie
  - `SystemConfig`
  - shared template state

4. Auth and access validation
- `verifyAuthWithOptions(...)` enforces:
  - `SignInRequired`
  - `SignOutRequired`
  - `AdminRequired`
  - cross-origin rules
  - inactive-user and forced-password-change constraints

5. Domain handler
- The request reaches `routers/web/...` or `routers/api/...`.
- Handlers should stay thin and delegate to `services/...`.

6. Business logic and persistence
- `services/...` orchestrate business rules.
- `models/...` read or write the DB and represent domain state.
- `modules/...` provide reusable infrastructure such as git, storage, cache, markup, logging, web helpers, SSH, and indexing.

7. Response
- Web:
  - templates from `templates/...`
  - optional page JS data for `web_src/js/...`
- API:
  - JSON or file responses through helpers in `services/context/`

## 4. Authentication Map

### 3.1 Where Auth Routes Live

Auth routes are mainly declared in `routers/web/web.go`, especially around:
- `/user/login`
- `/user/sign_up`
- `/user/two_factor/...`
- `/user/webauthn/...`
- `/user/openid/...`
- `/login/oauth/...`
- `/user/settings/security/...`
- `/user/settings/applications/oauth2/...`

### 3.2 Key Auth Files

- `routers/web/auth/auth.go`
  - classic login
  - signup
  - remember-cookie login
  - post-login redirect
  - branching toward 2FA or WebAuthn

- `routers/web/auth/password.go`
  - forgot password
  - reset password
  - forced password change

- `routers/web/auth/2fa.go`
  - TOTP
  - scratch codes

- `routers/web/auth/webauthn.go`
  - passkeys
  - WebAuthn challenge/assertion flow

- `routers/web/auth/openid.go`
  - OpenID sign-in
  - connect
  - register

- `routers/web/auth/oauth.go`
  - OAuth2 / OIDC provider login start and callback
  - link account
  - auto-registration
  - provider-data sync triggers

- `routers/web/auth/oauth_signin_sync.go`
  - post-login provider-data synchronization

- `routers/web/auth/oauth2_provider.go`
  - Gitea as an OAuth2 / OIDC provider
  - authorize, access token, userinfo, introspection, JWKS

- `routers/web/auth/linkaccount.go`
  - external-account linking to a local account

### 3.3 Classic Web Login Flow

1. Browser requests `/user/login`.
2. `context.Contexter()` prepares context and page data.
3. `newWebAuthMiddleware()` attempts authentication through available strategies:
  - OAuth2 header/bearer where allowed
  - Basic auth where allowed
  - reverse-proxy auth if enabled
  - session
  - SSPI on Windows if enabled
4. `auth.SignIn` renders the page.
5. `POST /user/login` enters `auth.SignInPost`.
6. On success, the flow may:
  - branch to 2FA
  - branch to WebAuthn
  - create a remember cookie
  - redirect to `redirect_to` or the default target
7. Inactive, blocked, or forced-password-change users are stopped by auth logic or `verifyAuthWithOptions(...)`.

### 3.4 Auth Services and UI

- `services/auth/` contains reusable auth strategies such as:
  - `Basic`
  - `OAuth2`
  - `Session`
  - `ReverseProxy`
  - `SSPI`

- Auth UI lives in `templates/user/auth/`
- Relevant browser-side auth code includes:
  - `web_src/js/features/user-auth-webauthn.ts`
  - `web_src/js/features/captcha.ts`

### 3.5 Where to Extend Auth

- New auth UI step:
  - `routers/web/auth/...`
  - `templates/user/auth/...`
  - optional `web_src/js/features/...`

- New authentication rule or source:
  - `services/auth/...`
  - optionally `models/auth/...`
  - integrate through `newWebAuthMiddleware()`

- New OAuth2/OIDC provider endpoint:
  - `routers/web/auth/oauth2_provider.go`
  - `services/oauth2_provider/...`

## 5. Change Entry Points

### 4.1 New Web Route

- Add handler in `routers/web/<domain>/`
- Register in `routers/web/web.go`
- If it has UI:
  - template in `templates/...`
  - optional JS/CSS in `web_src/...`

### 4.2 New API Route

- Add handler in `routers/api/v1/...` or the proper API subtree
- Mount through `routers/init.go` or the existing API router
- Use `services/context/` helpers for validation and response consistency

### 4.3 New Business Rule

- Orchestration in `services/<domain>/`
- Persistence in `models/<domain>/`
- Keep routing logic thin

### 4.4 New Template Data

- Put page-specific data in handlers or domain middleware
- Put global data there only if it is truly cross-cutting
- For data consumed by page JS, use `ctx.PageData`

### 4.5 New SSR Screen or UI Change

- Template in `templates/...`
- If client-side interaction is needed:
  - logic in `web_src/js/features/...`
  - styles in `web_src/css/...`

### 4.6 Global Navigation and Template Hooks

- Main top navigation:
  - `templates/base/head_navbar.tmpl`

- Extra global links without rewriting the standard navbar:
  - `templates/custom/`
  - `custom/extra_links` hook in `templates/base/head_navbar.tmpl`

- Repository header and main repo tabs:
  - `templates/repo/header.tmpl`

- Extra repo tabs without rewriting the standard header:
  - `custom/extra_tabs` hook in `templates/repo/header.tmpl`

- Repo submenu areas:
  - `templates/repo/navbar.tmpl`
  - `templates/repo/sub_menu.tmpl`

### 4.7 User, Org, Repo, and Admin Areas

- Repo:
  - `routers/web/repo/`
  - `services/repository/`, `services/pull/`, `services/issue/`, `services/git/`
  - `templates/repo/`

- User:
  - `routers/web/user/`
  - `routers/web/user/setting/`
  - `services/user/`
  - `templates/user/`
  - `templates/user/settings/`

- Org:
  - `routers/web/org/`
  - `services/org/`
  - `templates/org/`
  - `templates/org/settings/`

- Admin:
  - `routers/web/admin/`
  - support often spans `models/`, `services/`, and `modules/setting/`
  - `templates/admin/`

## 6. Frequent Task Shortcuts

- Login / signup / account recovery:
  - `routers/web/auth/`
  - `templates/user/auth/`
  - `services/auth/`
  - `models/auth/`
  - `models/user/`

- User settings / security / applications:
  - `routers/web/user/setting/`
  - `templates/user/settings/`

- Repository header / tabs / page chrome:
  - `templates/repo/header.tmpl`
  - `templates/repo/navbar.tmpl`
  - `templates/repo/sub_menu.tmpl`

- Top navigation / global links:
  - `templates/base/head_navbar.tmpl`
  - `templates/custom/`

- Packages:
  - `routers/api/packages/`
  - `services/packages/`
  - `models/packages/`

- Actions:
  - `routers/api/actions/`
  - `routers/web/repo/actions/`
  - `services/actions/`
  - `models/actions/`

## 7. Technology and Validation Notes

- Backend: Go
- Server-side rendering: Go `.tmpl` templates
- Frontend: TypeScript
- Vue components exist in the repo
- Styling: CSS, Tailwind CSS, Fomantic UI
- Frontend verification tooling: Vitest, Playwright, ESLint, Stylelint

For area-specific validation:
- Go:
  - `make fmt`
  - `make lint-go`
  - targeted Go tests
- TypeScript / frontend:
  - `make lint-js`
  - `make test-frontend` or targeted frontend tests when needed
- `go.mod` changes:
  - `make tidy`
  - targeted frontend tests when needed
- `go.mod` changes:
  - `make tidy`