gitea/.codex-context.md

Gitea Codex Context

Acest fisier este memoria persistenta Codex pentru acest proiect. Istoric complet al modificarilor: vezi ./.codex-history. Baza structurala folosita pentru acest context: ./.ai-structure.md.

Arhitectura generala

• Entry point-ul principal este main.go, care seteaza versiunea aplicatiei in setting.AppVer si porneste comenzile din cmd/.
• Pornirea serverului web trece prin cmd/web.go, iar initializarea globala a aplicatiei instalate se face in routers/init.go prin InitWebInstalled() si expunerea rutelor prin NormalRoutes().
• Rutele web sunt centralizate in routers/web/web.go, in special in Routes() si registerWebRoutes(...).
• Rutele API sunt montate din routers/init.go: /api/v1 pentru API public, /api/internal pentru rute private, plus zone separate pentru Packages si Actions atunci cand sunt activate.
• Organizarea pe domenii pentru routing este clara: routers/web/repo/, routers/web/org/, routers/web/user/, routers/web/admin/, routers/web/auth/, respectiv routers/api/v1/ si celelalte subtree-uri API.
• Modelele de date sunt in models/, grupate pe domenii. Zone importante: models/user/, models/repo/, models/issues/, models/auth/, models/organization/, models/packages/, models/project/, models/webhook/, models/actions/.
• Persistenta si infrastructura de baza pentru DB sunt in models/db/, iar migrarile in models/migrations/.
• Serviciile de business logic sunt in services/, cu exemple relevante in services/auth/, services/user/, services/repository/, services/pull/, services/mailer/, services/indexer/, services/webhook/, services/packages/, services/actions/.
• services/context/ leaga request-ul HTTP de sesiune, user, template data si middleware-ul specific Gitea.
• UI-ul server-side este randat din templates/, iar frontend-ul modern si codul browser-side sunt in web_src/.

Fluxul de autentificare

• Rutele de autentificare sunt definite in principal in routers/web/web.go, sub grupurile /user, /login/oauth si subgrupurile aferente pentru 2FA, WebAuthn, OpenID si OAuth2.
• Fisierele principale din routers/web/auth/ sunt:
• routers/web/auth/auth.go: login clasic, signup, auto-login din remember cookie, redirect dupa autentificare si orchestration-ul de baza pentru paginile de auth.
• routers/web/auth/password.go: forgot password, reset password si forced password change.
• routers/web/auth/2fa.go: TOTP si scratch codes pentru pasul secundar de autentificare.
• routers/web/auth/webauthn.go: autentificare WebAuthn si passkeys.
• routers/web/auth/oauth.go: start si callback pentru provideri OAuth2/OpenID Connect, link-account si auto-registration.
• routers/web/auth/oauth_signin_sync.go: sincronizarea datelor utilizatorului dupa autentificare OAuth2.
• routers/web/auth/oauth2_provider.go: endpoint-urile providerului OAuth2/OIDC pe care le expune Gitea.
• routers/web/auth/openid.go: fluxul OpenID pentru sign-in, connect si register.
• routers/web/auth/linkaccount.go: asocierea unui cont extern cu un cont local.
• Template-urile UI pentru auth sunt in templates/user/auth/.
• Modelele si serviciile care sustin acest flux sunt in principal in models/auth/, services/auth/, services/oauth2_provider/ si services/externalaccount/.

Tehnologii cheie

• Backend principal: Go, confirmat prin go.mod si majoritatea fisierelor din cmd/, routers/, models/, services/ si modules/.
• Templating server-side: Go templates .tmpl, confirmate in templates/.
• Frontend principal: TypeScript, confirmat in web_src/js/ si in fisierele de configurare precum vite.config.ts, vitest.config.ts, tailwind.config.ts si eslint.config.ts.
• Componente Vue exista in repo, confirmate de fisiere .vue si de @vitejs/plugin-vue din package.json.
• Stilizare: CSS in web_src/css/, plus Tailwind CSS si Fomantic UI.
• Testare si lint frontend: Vitest, Playwright, ESLint si Stylelint.
• Tooling suplimentar confirmat in structura repo: shell scripts, YAML, Dockerfile si Nix.
• Dependintele si resursele statice nu au fost analizate ca obiectiv functional, conform cerintei.

Puncte de extensie

• Pentru o ruta web noua: adauga handler-ul in subtree-ul potrivit din routers/web/, apoi inregistreaza ruta in routers/web/web.go in registerWebRoutes(...).
• Pentru o ruta API noua: extinde zona relevanta din routers/api/v1/ sau din alt subtree API deja folosit si monteaza ruta prin entrypoint-urile din routers/init.go.
• Pentru logica noua de business: adauga orchestration in services/ si accesul la date in models/, pastrand handler-ele din routers/ relativ subtiri.
• Pentru un tab nou in meniul principal global: editeaza templates/base/head_navbar.tmpl.
• Pentru linkuri globale suplimentare fara a modifica toata structura standard, exista hook-ul template custom/extra_links in templates/base/head_navbar.tmpl.
• Pentru un tab nou in meniul unui repository: editeaza templates/repo/header.tmpl.
• Pentru taburi custom de repo fara rescrierea structurii standard, exista hook-ul custom/extra_tabs in templates/repo/header.tmpl.
• Pentru submenu-uri din zona repo activity sau sumar repo: verifica templates/repo/navbar.tmpl si templates/repo/sub_menu.tmpl.
• Pentru zonele de setari user, org sau admin, punctele uzuale sunt template-urile din templates/user/settings/, templates/org/settings/, templates/admin/ si rutele aferente din routers/web/user/, routers/web/org/, routers/web/admin/.

Observatii utile

• Versiunea implicita a aplicatiei in build-ul din sursa curenta este development, definita in main.go si copiata in setting.AppVer.
• Structura proiectului separa clar entrypoint-urile, routing-ul, modelele, serviciile si template-urile, ceea ce face extinderile viitoare predictibile.