Docs Audit

This page tracks the current state of the documentation site: what was verified, what is still unconfirmed, known risks, and architecture decisions for future maintainers.

Locale coverage status

The documentation navigation is translated across all supported locales, but the content depth is not yet synchronized. English is the source of truth for the deeper page set.

Locale	Current coverage	Recommended next action
EN	Complete/deeper coverage: 31 MDX pages, including detailed child pages for API, backend, frontend, and architecture topics	Keep EN as the verified source while parity work continues
ES	Partial/top-level coverage: 17 MDX pages, mostly section landing pages	Translate or summarize the missing EN child pages, or mark each pending translation explicitly
EUS	Partial/top-level coverage: 17 MDX pages, mostly section landing pages	Translate or summarize the missing EN child pages, or mark each pending translation explicitly

Locale parity checklist

When adding a docs page, create or update the corresponding en, es, and eus content in the same change.
If a full translation is not ready, add the locale page with a translated heading and an explicit Translation pending / Traduccion pendiente / Itzulpena pendiente note.
Keep navigation, _meta.ts entries, and page links aligned across all three locales.

What was verified

The following claims were cross-referenced against the actual codebase under backend-js/, frontend-app/, and docs/:

Monorepo structure: three packages (backend-js, frontend-app, docs) under pnpm workspaces. Verified from pnpm-workspace.yaml.
Backend endpoint inventory: all endpoints in the API reference were verified against backend-js/src/app/api/*/route.ts files.
Auth flows: access token (Bearer JWT, 15 min) + refresh token (HTTP-only cookie, 7 days) confirmed from backend-js/src/app/lib/jwt.ts and backend-js/src/app/config/envConfig.ts.
Package state machine: pending → assigned → in_transit → delivered | undelivered | failed confirmed from backend-js/src/app/types/index.ts.
Email side effects on status change: confirmed from backend-js/src/app/lib/packageStatus/packageStatusSideEffects.service.ts.
Token types: refresh_token, tracking_token, reset_pwd_token, activate_account_token confirmed from backend-js/src/app/types/index.ts.
Database name inconsistency: schema.sql creates database as erronka; backend-js/.env.example documents it as pakag. Marked as Needs verification in environment docs.
Google Directions origin: coordinates hardcoded in backend-js/src/app/api/routes/create/service/create.service.ts — confirmed risk documented in security and environment pages.
Frontend API client file paths: all app/lib/api/* paths are referenced as documented; exact TypeScript type locations are verified from app/utils/types/api/.

What is still unverified (Needs verification)

The following items could not be confirmed without access to a running environment or full integration test:

Exact request/response payload schemas for admin-only endpoints that the current frontend does not call (/api/packages/create, /api/packages/update, /api/routes/create, etc.).
Pagination defaults for list endpoints (/api/packages/list, /api/users/list, /api/logs/listAll).
Error response variants beyond { error: string } — full error shape per status code.
Production domain and CORS configuration (documented as risk, not confirmed).
Activation URL: docs note it reuses RESET_BASE_URL; exact behavior in a live environment is unverified.
Frontend admin-facing UI screens: some screen locations referenced in domain/frontend pages could not be pinned to specific file paths.

Known risks

Severity	Risk	Reference
High	`JWT_SECRET` has a hardcoded fallback in `envConfig.ts` — if not set in production, the fallback is publicly visible in the repo	Security page, CLAUDE.md §4.2
High	`DEFAULT_USER_PASSWORD` has the same hardcoded fallback problem	Security page, CLAUDE.md §4.3
Medium	`handleError` forwards internal error messages to HTTP responses in 500 cases	CLAUDE.md §4.5
Medium	Rate limiting packages installed (`@upstash/ratelimit`) but not implemented	CLAUDE.md §7.2
Low	MySQL env vars are not validated at startup — silent failures possible	CLAUDE.md §4.4
Low	`GOOGLE_DIRECTIONS_API_KEY` uses TypeScript `!` assertion without a startup guard	CLAUDE.md §4.10

Docs site architecture decisions

Custom layout — the docs do not use nextra-theme-docs layout. Instead, a fully custom sidebar, header, and content layout is implemented in docs/app/[lang]/layout.tsx. This was chosen to allow full design control.
Locale routing — locale is the first URL segment (/en/, /es/, /eus/). Middleware at docs/middleware.ts redirects locale-less paths to /en/.
Search — implemented as a static client-side page-title search via DocsSearch.tsx. No full-text index. Ctrl+K / Cmd+K opens the search modal.
Table of contents — PageToc.tsx reads DOM headings after mount (scoped to .docs-content). Headings get stable IDs from the slugify function in mdx-components.tsx.
Mobile TOC — MobilePageTools.tsx renders a button below the header that opens a bottom drawer with the TOC and a shortcut to search.
i18n — dictionaries live in docs/app/i18n/. Adding a new nav item requires updating DocsDictionary interface and all three locale files.
MDX heading IDs — h2, h3, h4 MDX components are overridden in docs/mdx-components.tsx to auto-generate id attributes via slugify.

Build and search status

Feature	Status
Root `/` redirect to `/en`	Working via `docs/app/page.tsx` + middleware
Locale-prefixed routing	Working — `/en/`, `/es/`, `/eus/`
Locale fallback (e.g. `/backend` → `/en/backend`)	Working via `docs/middleware.ts`
Per-page TOC (desktop)	Working — right-side sticky via `PageToc.tsx`
Per-page TOC (mobile)	Working — bottom drawer via `MobilePageTools.tsx`
Ctrl+K search	Working — static title search via `DocsSearch.tsx`
Heading anchor links	Working — IDs generated via `slugify` in `mdx-components.tsx`
Code block copy button	Working — via `CodeBlock.tsx`
Mobile sidebar	Working — via `MobileMenu.tsx`
View transitions	Working — CSS view transitions on page navigation

How future agents should update docs

Adding a new backend endpoint: update docs/content/en/api/index.mdx. Add request/response examples. Verify from the actual route.ts and dtos/ files. Mark anything unverified with > [!NOTE] Needs verification.
Adding a new frontend page or hook: update docs/content/en/frontend/index.mdx.
Adding a new doc section or page: create/update the content in all three locale trees (docs/content/en/, docs/content/es/, and docs/content/eus/) in the same change. If full translation is not complete, add a translated heading and mark the page as Translation pending.
Keeping locale depth aligned: when EN gets a deeper child page, add matching ES/EUS placeholders or translations so the locale page counts and nav structure do not drift silently.
Fixing a broken link: all internal links should be locale-prefixed (e.g. /en/setup). Locale-less links also work via middleware redirect, but explicit locale links are preferred.
Keeping docs truthful: never document behavior that cannot be verified from the codebase. Use > [!NOTE] callouts with “Needs verification” for anything uncertain.