Handoff: docs-angular context, landing links, and moving private-project auth to cloud/MongoDB

This document captures what was verified in the codebase (March 2026) and recommended next steps. Product focus stays on the landing site (deploy/gograb-landing/); docs work is a separate track unless explicitly scoped.

1. What docs-angular is

• App path: apps/docs-angular/ (Nx app).
• Production routing: Hash-based URL strategy when environment.production is true — see provideRouter(..., withHashLocation()) in src/app/app.config.ts. Paths look like https://docs.gograb.space/#/select-project, not /docs on arbitrary hosts.
• Bootstrap: APP_INITIALIZER loads dynamic routes via DynamicRoutesService.generateDynamicRoutes(), then DocsAppModeService, then NGXS LoadPersistedProject. Routes are reset after generation (router.resetConfig).

Canonical public entry for marketing links

• Use: https://docs.gograb.space/#/select-project
• Avoid: relative /docs on the landing host (breaks on Cloudflare Pages previews and on file:// opens — resolves to file:///docs).

Landing repo alignment

• deploy/gograb-landing/index.html and test-versions/index-v8.html should use the absolute docs URL above for “Docs” CTAs.
• deploy/gograb-landing/DEPLOY.md documents this and optional View Session links.

2. Project list and selection (NGXS)

• State: src/app/state/project-selection.state.ts — ProjectSelectionState.
• Sources:
  • Local / dev: GET assets/docs-folders-config.json (with cache-busting).
  • Cloud mode: folders config via DocsApiService / cloud (LoadAvailableProjects branches on docsAppMode.docsAppMode() === 'cloud').
• Persistence: Selected project in localStorage under docs-selected-project (JSON). NGXS storage plugin also persists projectSelection / projectDocs.
• Root projects: Only folder nodes with isRoot: true under each language (english / spanish) become selectable “projects.” Nodes with password but without isRoot are containers, not projects (skipped in ProjectSelectionState and AccessService.deriveProjectsFromFoldersConfig).

3. View sessions (subset of projects via share link)

Purpose: Restrict which projects appear for a given link (e.g. partner or public subset) without exposing the full catalog.

Frontend

• URL patterns parsed in ProjectSelectionState.getViewSessionContextFromUrl():
  • Query: ?v=, ?session=, ?vs=, ?go=
  • Hash: #/v/:token, #/share/:token, #/go/:slug
• Routes in DynamicRoutesService.getBaseRoutes(): v/:token, share/:token, go/:slug → ViewSessionEntryComponent, which redirects to select-project with the right query params.
• Admin-generated links (src/app/admin/view-sessions/view-sessions.component.ts): buildShareableLink() → origin/#/v/{token} or origin/#/go/{slug}.

Backend

• APIs/backend-docs-api/src/app/view-sessions/view-sessions.controller.ts
  • Public: GET /sessions/:token, GET /sessions/by-slug/:slug → { allowedProjectIds }
  • Admin: list/create/deactivate (roles: exec/dev/admin/system).

Client API base

• ProjectSelectionState resolves view sessions against DOCS_API_URL (must be backend-docs-api, e.g. /docs-api or https://docs-api.gograb.space/... depending on deploy). Wrong base = silent filter failure.

4. Private projects and passwords (current design — to improve)

Where passwords live today

• File: apps/docs-angular/src/assets/docs-folders-config.json
• Shape: Under folders[] → language folder → children[]: each root project may include "password": "<plaintext>". Presence of password implies private visibility in derived metadata.
• Cloud: Same JSON may be served from the docs API in cloud mode — deployed config can differ from git.

Runtime behavior

• AccessService (src/app/services/access.service.ts):
  • deriveProjectsFromFoldersConfig() builds DocsProject[] with visibility: 'private' when password is set.
  • unlockProject(projectId, inputPassword) compares trimmed plaintext equality: expected === inputPassword.
  • Unlock flags: localStorage keys docs-project-unlocked:{projectId} and cross-language docs-project-unlocked:{projectName}.
  • matchPrivateProjectsByPassword() powers “View Private Projects” modal (private-project-modal) — finds all private root projects whose password exactly matches.
• Security posture: Passwords are effectively public in the client bundle/config for anyone who can read docs-folders-config.json or the cloud payload. This is acceptable only for low-friction gating, not real secrecy.

UI touchpoints

• src/app/shared/private-project-modal/ — bulk password search.
• project-switcher, docs-page, project-selection — per-project unlock flows.

5. Recommendations: move private access to cloud/MongoDB (next agent)

Goals

1. No plaintext passwords in browser-loaded JSON; optionally no password field in folders config at all.
2. Server-side verification (e.g. POST /docs-api/projects/:id/unlock with password body, or session cookie/JWT after success).
3. MongoDB (or existing docs DB) stores hashed credentials per project or per “doc space,” with audit fields (createdBy, rotatedAt).

Suggested phases

Risks to call out

• CDN caching: If folders config is cached, coordinate cache busting after migration.
• Offline/local dev: Keep a dev-only path or mock, or point to staging API.
• Cross-domain: Cookies must match docs.gograb.space / API subdomain policy; CORS already sensitive for docs-api.

6. Key files (quick map)

7. Explicitly out of scope for “landing-focused” work

• Implementing MongoDB or backend unlock APIs from the landing repo alone.
• Changing docs-angular auth without coordinating backend-docs-api deploy and CORS.

Landing owner checklist (only)

• Docs buttons point to https://docs.gograb.space/#/select-project (or a View Session URL from admin if curating projects).
• Do not use relative /docs for static deploys that are not reverse-proxied to the docs app.

8. Related internal docs

• docs/english/Docs-angular/docs-auth-implementation.md — auth patterns (may need update after server-side private unlock).
• docs/english/Docs-angular/plan-dynamic-docs-visibility.md — visibility (align with new model).

End of handoff. Next agent: pick up Phase A–B in backend-docs-api + schema repo, then wire AccessService in docs-angular.