# CLAUDE.md — Repository Memory

> Entry point Claude Code reads on every session. Keep this under 400 lines. Long context belongs in [`.claude/context/`](.claude/context/) (added in Phase 7).

## 1. What this repo is

LOMA-PORTAL — an AI-first enterprise portal generated from the `enterprise-genesis` meta-template. The template is owned by Loma Group's platform team and is the single source of truth for new product repos.

Two repos to keep separate in your head:

- **`enterprise-genesis`** — the factory (this template). Touched only when evolving the platform.
- **`loma-portal`** (and siblings) — products spawned from the factory via `_init.ps1`.

## 2. Tech stack

| Layer      | Primary                                                      | Secondary               |
| ---------- | ------------------------------------------------------------ | ----------------------- |
| Frontend   | Angular 19 (Signals, Standalone)                             | Next.js 15 (App Router) |
| Backend    | .NET 9 ASP.NET Core (Clean Arch + MediatR + EF Core)         | NestJS 11               |
| DB         | PostgreSQL 16 (Prisma)                                       | SQL Server 2022 (EF)    |
| Cache      | Redis 7                                                      | —                       |
| Realtime   | SignalR + WebSocket                                          | —                       |
| Queue      | Hangfire (.NET) + BullMQ (Node)                              | —                       |
| Auth       | JWT + Refresh, RBAC, single-tenant                           | —                       |
| UI         | Tailwind + Angular Material, `premium` theme, dark mode, PWA | —                       |
| i18n       | English + Thai                                               | —                       |
| Deployment | Docker + Kubernetes (GitLab CI primary)                      | —                       |
| AI         | Claude Opus, strict governance                               | —                       |
| Compliance | PDPA + GDPR + Audit trail                                    | —                       |

## 3. Folder map (one-line per folder)

```
apps/                  Deployable apps (web-angular, web-next, api-nest, worker-nest, admin, mobile)
packages/              Shared TS libs (tsconfig, eslint-config, design-tokens, ui-angular, ui-react, api-contracts)
dotnet/                .NET solution — deliberate deviation from §14 apps/api-dotnet/; top-level placement chosen because .NET solutions contain multiple projects (Api / Application / Domain / Infrastructure / Shared) and don't fit the single-app apps/ pattern. See ADR-0011.
prisma/                Postgres schema source of truth + seed.ts
database/              SQL Server raw SQL: migrations, procedures, functions, views, seeds, scripts
enterprise-modules/    Reusable business modules: auth, rbac, audit, notifications, file-storage
platform/              docker/, k8s/, nginx/, terraform/, observability/, secrets/ (template only)
config/                Cross-app config schemas
docs/                  Human docs: architecture/, decisions/ (ADRs), onboarding/, runbooks/, api/, compliance/
knowledge/             AI knowledge base: architecture/, business/, workflows/, patterns/, anti-patterns/, decisions/
.claude/               Claude Code workspace: settings, hooks, commands, agents, skills, blueprints, prompts, orchestrators
.mcp/                  MCP server configs, profiles, policies
tools/                 validators/, generators/, codemods/
presets/               stacks/, business/, themes/ — used by _init.ps1
marketplace/           Internal asset registry (future)
analytics/             Product analytics integration (future)
telemetry/             Telemetry env overrides + dashboards-as-code source
```

## 4. Architecture principles

1. **Direction of dependencies:** `apps/ → packages/ → enterprise-modules/`. Never the reverse, never sideways between apps.
2. **Clean Architecture in .NET:** `Api → Application → Domain ← Infrastructure`. Domain has zero external deps.
3. **Standalone Angular + Signals.** No NgModules. No `HttpClient` in components. State via Signals + facade.
4. **API response shape is one shape:** `{ success, message, data }` + `{ page, pageSize, total }` for lists.
5. **EF reads:** `AsNoTracking() + .Select()` directly to response DTOs. Never fetch-then-map.
6. **Soft delete with `deletedAt`** + audit fields (`createdAt`, `updatedAt`, `createdBy`, `updatedBy`) on all entities.
7. **Centralize constants.** No magic strings. Place under `constants/` in each app.
8. **i18n always.** UI text never hardcoded — Transloco for Angular, next-intl for Next.js.
9. **AI-readable first.** Every folder has a README. Every commit message is conventional.
10. **Surgical changes.** No speculative features, no premature abstractions, no backwards-compat shims unless asked.

## 5. Naming conventions

- **Backend (.NET):** `{Entity}Controller`, `{Action}{Entity}Request`, `{Entity}{Type}Response`. PascalCase types, camelCase locals.
- **Backend (Nest):** `{name}.controller.ts`, `{name}.service.ts`, `{name}.module.ts`, `{name}.dto.ts`.
- **Frontend (Angular):** `{name}.component.ts` + `.html` + `.scss`, `{name}.service.ts`, `{name}.guard.ts`, `{name}.interceptor.ts`, `{name}.model.ts`.
- **Frontend (Next):** `app/(group)/path/page.tsx`, `app/api/path/route.ts`, kebab-case folders.
- **Branches:** `feat/...`, `fix/...`, `refactor/...`, `docs/...`.
- **Commits:** Conventional Commits (`feat:`, `fix:`, `chore:`, ...). Phase commits use `phase-<N>: <title> ✅`.

## 6. Commit conventions

- Commitlint enforces Conventional Commits (`commitlint.config.js`).
- Husky runs `pre-commit` (secret scan + format) and `commit-msg` (commitlint) and `pre-push` (`pnpm validate`).
- Never bypass hooks with `--no-verify`.

## 7. Where to find...

| You need...                | Look in...                                             |
| -------------------------- | ------------------------------------------------------ |
| Feature blueprints         | `.claude/blueprints/` (Phase 7)                        |
| ADRs                       | `docs/decisions/` (Phase 9)                            |
| Knowledge base             | `knowledge/` (Phase 7)                                 |
| MCP server configs         | `.mcp/servers/` + `.mcp/profiles/` (Phase 7)           |
| Repo intelligence map      | `tools/validators/repository-map.json` (Phase 7)       |
| Onboarding (EN/TH)         | `docs/onboarding/README.md` + `README.th.md` (Phase 9) |
| Runbooks (deploy, DR, ...) | `docs/runbooks/` (Phase 9)                             |
| Compliance docs            | `docs/compliance/` (Phase 8)                           |

## 8. "Before you code" checklist

1. Read this file + the relevant `CLAUDE.md` if one exists in the subfolder (Phase 3+ adds layer-specific files).
2. Check `docs/decisions/` for ADRs that constrain your area.
3. Check `knowledge/anti-patterns/` (Phase 7) for what NOT to do.
4. Match conventions in §4–§6.
5. Run `pnpm validate` before staging.

## 9. Agents and commands

Agents (Phase 7) live under `.claude/agents/`. Commands under `.claude/commands/`. Orchestrators chain them. See [`AGENTS.md`](AGENTS.md) for the roster and trigger phrases.

Until Phase 7 materializes, the agent works without sub-agents — but should still respect this file's rules.

## 10. Forbidden actions

- Editing `.env*`, `appsettings.*.json`, `platform/secrets/**`.
- Running `rm -rf`, `git push --force`, `git reset --hard`, `git clean -fd`, `git checkout -- .`, `git restore .`.
- Bypassing hooks (`--no-verify`, `--no-gpg-sign`, ...).
- Committing real secrets or credentials.
- Generating speculative code "while we're here."
- Adding backwards-compat shims unless the user explicitly asks.

These are mirrored as hard denies in [`.claude/settings.json`](.claude/settings.json).

## 11. Day-1 acceptance criteria

A working repo means:

1. `pnpm install` succeeds.
2. `docker compose up -d` brings Postgres, Redis, SQL Server to healthy.
3. `pnpm dev` runs frontend + backend on documented ports.
4. Claude Code loads this file with no warnings.
5. `pnpm validate` passes (lint + format + repo-map + arch + deps).
6. `pnpm test` passes seeded tests.
7. Browser opens the login screen, seeded admin signs in, dashboard shell renders.
8. `docs/onboarding/README.md` (EN) + `README.th.md` (TH) are accurate.

If any of those fails, the repo is not Day-1-complete. Stop and fix before adding features.

## 12. Phased generation status

| Phase | Title                                    | Status                   |
| ----- | ---------------------------------------- | ------------------------ |
| 0     | Pre-flight                               | Done                     |
| 1     | Monorepo Foundation                      | Done                     |
| 2     | Preset System                            | Done                     |
| 3     | Frontend Foundations                     | Done                     |
| 4     | Backend Foundations                      | Done                     |
| 5     | Prisma + Database Foundations            | Done                     |
| 6     | Enterprise Modules                       | Done                     |
| 7     | AI Layer                                 | Done                     |
| 8     | DevOps, Testing, Observability, Security | Done                     |
| 9     | Documentation & Onboarding               | Done — template complete |

When a phase completes, update this table.

## Known Issues

- web-next production build: see [`docs/known-issues/web-next-prod-build.md`](docs/known-issues/web-next-prod-build.md). Upstream Next.js framework bug — `pnpm dev` and the primary Angular frontend are unaffected.

## 13. Links

- Master prompt: [`GENESIS.md`](GENESIS.md)
- Resolved plan: [`GENESIS-PLAN.md`](GENESIS-PLAN.md)
- Bootstrap runbook: [`RUNBOOK.md`](RUNBOOK.md)
- Agent roster: [`AGENTS.md`](AGENTS.md)
- Contributing guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Security policy: [`SECURITY.md`](SECURITY.md)
