Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 67 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,70 @@ Owns the Angular public website, operator dashboard and embeddable authenticatio

Start with the canonical [work state](../user-proxy/docs/WORK-STATE.md), [architecture](../user-proxy/docs/ARCHITECTURE.md), [capabilities](../user-proxy/docs/CAPABILITIES.md), [development](../user-proxy/docs/DEVELOPMENT.md), [security](../user-proxy/docs/SECURITY-OPERATIONS.md) and [design](../user-proxy/docs/DESIGN.md). Preserve existing README contribution rules and DESIGNGUIDE.md. Read widget integration/event guides before changing the custom element contract.

- Branch workflow: use `production` as the frontend base and PR target. Before pushing a feature branch or opening its PR, fetch and merge the latest `origin/production` into that feature branch. Keep release branches unchanged until PR review.
- Inspect status/diff; preserve unrelated changes. New application code uses TypeScript and existing standalone Angular patterns. Use Angular CLI scaffolding when practical; never change architecture solely to satisfy scaffolding.
- Install from lock using `npm ci --ignore-scripts --legacy-peer-deps`; generate ignored env modules with `node tools/set-env`. Review environment base URLs before starting: local config defaults to a remote test API.
- Run `node --test tools/tests/*.test.cjs`, affected builds and `git diff --check`. Existing Nx/Jest targets have known gaps: report exact commands and limitations in canonical work state.
- Keep error, denied, empty and loading states distinct; provide retry. Never render request data as HTML or log/store tokens. Client visibility does not replace server authorization.
- Update the single backend-owned capability matrix and work state alongside changes. Product/architecture guidance is linked, not duplicated here. Public claims require evidence; do not invent SLAs, guarantees or future functional controls.
## Commands

| Task | Command |
|---|---|
| Install | `npm ci --legacy-peer-deps` (Node 20; peer deps conflict without the flag) |
| Env setup | `cp .env.example .env` and fill in the values. `tools/set-env.js` generates the git-ignored env-variables.ts for each app ([docs/environment.md](docs/environment.md)) |
| Run dashboard | `npm start` (port 4200) |
| Run widget alone | `npm run start:proxy-auth` (also port 4200) |
| Build widget into dashboard assets | `npm run build:proxy-auth` |
| Full build | `npm run build:test`, `npm run build:stage` or `npm run build:prod`. Plain `npm run build` mixes a prod widget with a local dashboard |
| Format | `npm run format:code`. Prettier also runs on pre-commit through husky and lint-staged |

`npm test` and `npm run lint` are not reliable at this commit: there is no test target on the dashboard, and `nx workspace-lint` is gone in Nx 21. Check a change by building the affected app: `npx nx build 36-blocks` or `npx nx build 36-blocks-widget` (run `node tools/set-env` first). The CI "Build check" workflow fails on every PR today because it never runs `set-env`, so a red check there says nothing about your change ([docs/environment.md](docs/environment.md#ci-githubworkflowsmainyml-build-check)).

## Read before you change

- Anything → [docs/architecture.md](docs/architecture.md), then [docs/conventions.md](docs/conventions.md); why things are shaped this way → [docs/decisions.md](docs/decisions.md)
- The widget's public API, events or build → [docs/modules/widget-embed.md](docs/modules/widget-embed.md) and [docs/api.md](docs/api.md#widget-public-api-host-page--widget)
- Widget login, register or OTP → [docs/modules/widget-auth.md](docs/modules/widget-auth.md), [docs/flows/widget-verification.md](docs/flows/widget-verification.md)
- Widget account screens → [docs/modules/widget-account.md](docs/modules/widget-account.md)
- Dashboard login, token or guards → [docs/modules/app-shell.md](docs/modules/app-shell.md), [docs/flows/dashboard-login.md](docs/flows/dashboard-login.md)
- Blocks (features) wizard, OAuth clients, client secrets, redirect response mode → [docs/modules/panel-features.md](docs/modules/panel-features.md), [docs/flows/feature-configuration.md](docs/flows/feature-configuration.md)
- Users, logs, billing, dashboard, layout → [docs/modules/panel-ops.md](docs/modules/panel-ops.md)
- `libs/**`, HTTP, the interceptor → [docs/modules/shared-libs.md](docs/modules/shared-libs.md)
- Routes, state, components, styling → [docs/ui/](docs/README.md#ui)
- A common change (page, backend call, block tab, widget key or screen, env value, lib, release) → [docs/recipes.md](docs/recipes.md)

## Rules

1. Never rename or remove any part of the widget's public contract:
- `window.initVerification` and the `proxy-auth` tag
- `window.__proxyAuth` and the `openAddUserDialog` event
- the `userProxyContainer` id and the assets/proxy-auth/proxy-auth.js path
- any value in `libs/constant/src/verification/verification.ts`

Customer sites depend on all of these. Add new values instead ([docs/api.md](docs/api.md)).
2. No dynamic `import()` in `apps/36-blocks-widget`. `build-elements.js` leaves the `chunk-*` file it creates out of the single-file bundle, so the bundle breaks on host pages.
3. A new `initVerification` config key that must not be sent to the backend goes into `RESERVED_KEYS` in `apps/36-blocks-widget/src/app/init-verification.ts`. Every other key is POSTed as `otherData` ([recipe](docs/recipes.md#add-an-initverification-config-key)).
4. Put widget CSS in component styles. `apps/36-blocks-widget/src/styles.scss` is also injected into the host page's `<head>`. Build overlays with `WidgetPortalService` / `WidgetDialogService`.
5. Set and clear the dashboard token only through `AuthService.setTokenSync` / `clearTokenSync`. They keep the `authToken` cookie and the in-memory `IToken` in sync. Guards read both, HttpWrapper reads memory, and ErrorInterceptor reads only the cookie ([docs/modules/app-shell.md](docs/modules/app-shell.md)).
6. A dashboard endpoint called without a session must be on the ErrorInterceptor allow-list. Otherwise it is silently dropped (`EMPTY`) ([docs/modules/shared-libs.md](docs/modules/shared-libs.md)).
7. A 200 can still be an error. Check `res.hasError` (dashboard) or the per-endpoint success field (widget) as well as using `catchError` ([docs/conventions.md](docs/conventions.md#http-and-errors)).
8. A block has two ids: numeric `id` for feature CRUD, OAuth, scopes and client secrets, and string `reference_id` for the widget, billing and the Users/roles screens. Passing the wrong one fails silently ([docs/glossary.md](docs/glossary.md)).
9. In the widget, copy `OtpService.options` before adding per-call headers. It is one shared mutable object, and its headers leak into later calls.
10. The widget must not import `@proxy/services/proxy/*`, `@proxy/services/httpWrapper` or the login service. They need `AngularFireAuth` and `IToken`, which only the dashboard provides.
11. Add dashboard pages to `apps/36-blocks/src/app/panel/panel.routes.ts`. `apps/36-blocks/src/app/panel/layout/layout.routes.ts` is dead (nothing imports it).
12. Never send a client id. The current client is stored on the server against the token, and switching client is `POST switchclient` followed by a full page reload.
13. Everything `tools/set-env.js` writes ends up in a public browser bundle. Never add a real server-side secret there. When you add a key, also add it to `.env.example`.
14. Keep the `setTimeout(…, 100)` before block create/update in `create-feature.component.ts`. The payload is filled in by promises (file reads, chip lists) ([docs/modules/panel-features.md](docs/modules/panel-features.md)).
15. Branch flow is `<card>-clean` → `stage` → `production`; the README's `development`/`main` flow is stale. PRs into `stage` get **no CI build**, so build locally first. Land any revert on `stage` too ([docs/conventions.md](docs/conventions.md#branching-and-release)).

## Where things are

- `apps/36-blocks/src/app/website/`: public marketing pages, login and register
- `apps/36-blocks/src/app/panel/`: the logged-in `/app` dashboard pages, each with a `<page>.store.ts` ComponentStore
- `apps/36-blocks/src/app/core/`: the root NgRx store, the auth initializer, client registration
- `apps/36-blocks-widget/src/app/init-verification.ts`: the widget's global API
- `apps/36-blocks-widget/src/app/otp/`: widget screens, the `otp` store, `OtpService`
- `apps/36-blocks-widget/build-elements.js`: post-build step that produces the single proxy-auth.js
- `libs/`: shared code, imported only through the `@proxy/...` aliases in `tsconfig.base.json`
- `tools/set-env.js`, `tools/postbuild.js`: env generation and the version.json writer
- `apps/shared/scss/`: global SCSS and Tailwind entry shared by both apps

## Docs map

See [docs/README.md](docs/README.md) for every doc and when to read it. What the code can't answer is listed in [docs/open-questions.md](docs/open-questions.md); don't guess at those, ask.
When you change behaviour that a doc describes, update that doc in the same change and run `/ai-docs update`.
2 changes: 1 addition & 1 deletion docs/.ai-docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"skill": "ai-docs",
"skill_version": "0.1.0",
"created": "2026-10-14",
"last_run": { "mode": "init", "commit": "76f26ae5", "date": "2026-10-14" },
"last_run": { "mode": "update", "commit": "395659d5", "date": "2026-10-29" },
"superseded": [
"docs/widget-window-events.md",
"docs/widget-script-loading.md",
Expand Down
39 changes: 17 additions & 22 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
verified_at: 76f26ae5
verified_on: 2026-10-14
verified_at: 395659d5
verified_on: 2026-10-29
---
# Docs index

Expand All @@ -16,6 +16,8 @@ Start with [../AGENTS.md](../AGENTS.md), then read the doc for the area you're c
| [api.md](api.md) | You're touching the widget's public JS API (`initVerification`, callbacks, window events) or any backend call |
| [environment.md](environment.md) | You're running or building locally, adding an env key, or touching CI or `tools/` |
| [recipes.md](recipes.md) | You're making a common change: a page, a backend call, a block tab, a widget config key or screen, an env value, a lib, a release |
| [decisions.md](decisions.md) | You want to know why something is built the way it is before changing it: the single-file widget, two HTTP wrappers, build-time config, per-page stores, no Nx Cloud |
| [open-questions.md](open-questions.md) | You hit something the code can't explain. Every open question for a human, linked to the doc that holds the detail |

## Modules

Expand Down Expand Up @@ -52,23 +54,16 @@ The older notes (docs/widget-*.md, docs/build-modernization.md, docs/angular-*.m

## Needs a human

Open questions the code can't answer. Answer them in the doc that asks, then delete the TODO.

- **Branching:** which branch to cut `-clean` from, and whether `main` and `development` are retired ([conventions.md](conventions.md#branching-and-release)).
- **Deploy and CI:**
- the deploy target and the branch-to-environment mapping ([architecture.md](architecture.md#build), [environment.md](environment.md))
- whether CI "Build check" passes ([environment.md](environment.md))
- whether the `postbuild.js` hash regex matches upper-case hashes ([environment.md](environment.md))
- whether stage `production: false` is intended ([environment.md](environment.md))
- **SSR:** why it was removed, and whether the leftover files can be deleted ([modules/app-shell.md](modules/app-shell.md)).
- **Auth:**
- whether the backend rejects `Bearer` ([modules/shared-libs.md](modules/shared-libs.md))
- the missing redirect after email login, and whether `/login` can return 401 ([flows/dashboard-login.md](flows/dashboard-login.md))
- **Widget:**
- client-side AES with static keys ([modules/widget-auth.md](modules/widget-auth.md))
- whether MSG91 and callback errors should reach the host's `failure` ([modules/widget-auth.md](modules/widget-auth.md), [flows/widget-verification.md](flows/widget-verification.md))
- whether Tailwind preflight leaks into host pages, and whether `webpack.config.js` is dead ([modules/widget-embed.md](modules/widget-embed.md))
- which backend permissions guard the role/permission endpoints, and the future of the `subscription` type ([modules/widget-account.md](modules/widget-account.md))
- **Blocks:** whether `feature_id` 1/2 are stable, and the dead Lago helpers ([modules/panel-features.md](modules/panel-features.md)).
- **Panel:** whether Logs is still a supported product, and which payment provider sits behind checkout ([modules/panel-ops.md](modules/panel-ops.md)).
- **UI:** the rule for where state goes ([ui/state.md](ui/state.md)) and the `@apply` opacity limit ([ui/design-system.md](ui/design-system.md)).
Open questions the code can't answer are collected in [open-questions.md](open-questions.md), and each one is also a `[!TODO]` in the doc it concerns. Answer it in that doc, then delete the TODO and the line in open-questions.md.

## Where the standard doc names live

Some agent guides expect files named ARCHITECTURE, FLOWS, CONFIGURATION, DECISIONS and OPEN_QUESTIONS. In this repo they map to the existing lower-case files, so there is one source of truth per topic and no case-only name clashes on case-insensitive file systems:

| Expected | Here |
|---|---|
| ARCHITECTURE.md (modules, data, who calls whom) | [architecture.md](architecture.md), with per-module detail in [modules/](#modules) |
| FLOWS.md (main flows step by step) | [flows/](#flows): [dashboard-login](flows/dashboard-login.md), [feature-configuration](flows/feature-configuration.md), [widget-verification](flows/widget-verification.md) |
| CONFIGURATION.md (every setting and env var) | [environment.md](environment.md) |
| DECISIONS.md | [decisions.md](decisions.md) |
| OPEN_QUESTIONS.md | [open-questions.md](open-questions.md) |
8 changes: 5 additions & 3 deletions docs/api.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
covers: ["apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/otp/service/otp.service.ts", "apps/36-blocks-widget/src/app/otp/service/urls/**", "apps/36-blocks-widget/src/app/otp/service/user-management-bridge.service.ts", "libs/constant/src/widget-events.ts", "libs/urls/**", "libs/services/proxy/**", "libs/services/login/**", "apps/36-blocks/src/app/panel/billing/billing.urls.ts", "apps/36-blocks/src/app/panel/billing/billing.service.ts", "apps/36-blocks/src/app/app.config.ts"]
verified_at: 76f26ae5
verified_on: 2026-10-14
verified_at: 395659d5
verified_on: 2026-10-29
---
# API

Expand Down Expand Up @@ -150,7 +150,7 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header.
| PUT / DELETE | `/:referenceId/cPermission/:id` | `updatePermission` / `deletePermission` |

## Dashboard: features (blocks) configuration
`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md).
`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, `apps/36-blocks/src/app/panel/features/client-secrets/client-secrets.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md).

<!-- verify:ignore-start -->
| Method | Path | Service method |
Expand All @@ -165,6 +165,8 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header.
| GET / PUT / DELETE | /features/:featureId/oauthConfigs/:oauthConfigId | `getOauthConfig` / `updateOauthConfig` / `deleteOauthConfig` |
| POST | /features/:featureId/oauthConfigs/:oauthConfigId/regenerateSecret | `regenerateOauthSecret` |
| POST | /features/:featureId/oauthConfigs/:oauthConfigId/disable | `disableOauthConfig` |
| GET / POST | /features/:featureId/clientSecrets | `getClientSecrets` / `createClientSecret` (plaintext `client_secret` only in this response) |
| DELETE | /features/:featureId/clientSecrets/:secretId | `revokeClientSecret` (revokes; the secret stays listed with `revoked_at`) |
| GET / POST | /features/:featureId/blockScopes | `getBlockScopes` / `createBlockScope` |
| PUT / DELETE | /features/:featureId/blockScopes/:blockScopeId | `updateBlockScope` / `deleteBlockScope` |
| GET / POST | /subscription/:refId/billableMetrics | `getAllBillableMetrics` / `createBillableMetric` |
Expand Down
6 changes: 4 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
covers: ["apps/36-blocks/src/main.ts", "apps/36-blocks/src/app/app.config.ts", "apps/36-blocks/src/app/app.routes.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/build-elements.js", "apps/*/project.json", "tsconfig.base.json", "nx.json", "tools/*.js"]
verified_at: 76f26ae5
verified_on: 2026-10-14
verified_at: 395659d5
verified_on: 2026-10-29
---
# Architecture

Expand Down Expand Up @@ -121,6 +121,8 @@ flowchart LR

## Decisions and history

The full list, with evidence for each, is in [decisions.md](decisions.md). The ones that shape this page:

- **One file for the widget.** Customers paste one `<script>` tag, so `build-elements.js` concatenates polyfills → vendor → scripts → main, skips `chunk-*` files and inlines the CSS. A dynamic `import()` creates an ESM chunk that breaks this, which is why the widget has none (lesson from the March 2026 build fixes).
- **Shadow DOM for the widget.** `ProxyAuthWidgetComponent` uses `ViewEncapsulation.ShadowDom`, and overlays get their own shadow hosts on `document.body`, so host-page CSS can't break the widget. See [modules/widget-embed.md](modules/widget-embed.md).
- **Angular upgrades went one major version at a time**, on separate branches (`angular-v18-migration`, `angular-v21-migration`), because any change to the bundle or CSS can silently break customer sites. `@angular/fire` must move in lockstep with Angular. The Firebase compat API is still in use, so moving to the modular API is still pending.
Expand Down
6 changes: 3 additions & 3 deletions docs/conventions.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
covers: [".prettierrc.json", "package.json", ".husky/pre-commit", "apps/*/.eslintrc.json", ".eslintrc.json", ".github/workflows/main.yml", "tsconfig.base.json"]
verified_at: 76f26ae5
verified_on: 2026-10-14
verified_at: 395659d5
verified_on: 2026-10-29
---
# Conventions

Expand Down Expand Up @@ -59,7 +59,7 @@ The flow used in practice, from merged PRs #620–#661:
3. Release with `stage` → `production`. If that conflicts, use a `<card>-prod` branch → `production`. Hotfixes sometimes go straight to `production`; any revert must also land on `stage`, or the next release brings the change back (this happened with the retry interceptor, #642 → #639).

> [!WARNING]
> `README.md` still describes `development` → `main` → `production`. `main` (last merged 2026-04-21) and `development` (2026-04-27) are stale. `.github/workflows/main.yml` runs only on PRs to `development`, `main` and `production`, so **PRs into `stage` get no CI build**. Build locally before you open one.
> `README.md` still describes `development` → `main` → `production`. `main` (last merged 2026-04-21) and `development` (2026-04-27) are stale. `.github/workflows/main.yml` runs only on PRs to `development`, `main` and `production`, so **PRs into `stage` get no CI build**. Where it does run, it currently fails on every PR because `env-variables.ts` is never generated ([environment.md](environment.md#ci-githubworkflowsmainyml-build-check)). Build locally before you open one.

> [!TODO] Needs a human: confirm which branch new `-clean` branches should be cut from now (`stage` or `production`), and whether `main` / `development` are retired.

Expand Down
Loading
Loading