petru/gitea
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 2 Wiki Activity
Files
471cfdd1613544dee502fa97f903a76beedcbe06
gitea/.codex-project-map.md
T

9.8 KiB
Raw Blame History

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(...).
  1. cmd/web.go
  • newWebCommand() defines the web command.
  • runWeb(...) prepares graceful shutdown.
  • serveInstalled(...) calls routers.InitWebInstalled(...) and then routers.NormalRoutes().
  1. 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.
  1. Core middleware
  • common.MustInitSessioner() prepares the session.
  • context.Contexter() builds the web context and template data.
  • newWebAuthMiddleware() resolves optional or required authentication.
  1. 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
  1. Auth and access validation
  • verifyAuthWithOptions(...) enforces:
    • SignInRequired
    • SignOutRequired
    • AdminRequired
    • cross-origin rules
    • inactive-user and forced-password-change constraints
  1. Domain handler
  • The request reaches routers/web/... or routers/api/....
  • Handlers should stay thin and delegate to services/....
  1. 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.
  1. 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
  1. auth.SignIn renders the page.
  2. POST /user/login enters auth.SignInPost.
  3. On success, the flow may:
  • branch to 2FA
  • branch to WebAuthn
  • create a remember cookie
  • redirect to redirect_to or the default target
  1. 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
Reference in New Issue View Git Blame Copy Permalink