# Onboarding (English)

> Day-1 walkthrough — clone to running app in ≤ 5 minutes. Thai mirror: [`README.th.md`](README.th.md).

## Prerequisites

| Tool             | Version                                               | Verify                                         |
| ---------------- | ----------------------------------------------------- | ---------------------------------------------- |
| Node.js          | ≥ 20.12.0 (recommend 20.18.0 LTS, pinned in `.nvmrc`) | `node --version`                               |
| pnpm             | ≥ 9.0.0                                               | `pnpm --version`                               |
| .NET SDK         | 9.x                                                   | `dotnet --version`                             |
| Docker + Compose | 24.x+                                                 | `docker --version` && `docker compose version` |
| Git              | 2.40+                                                 | `git --version`                                |

Install pnpm if missing: `npm install -g pnpm`. Everything else is platform-installer.

## 1. Get the code (≤ 30 s)

```bash
git clone <repo-url> loma-portal
cd loma-portal
```

## 2. Install (≤ 90 s on a warm cache)

```bash
pnpm install
cd dotnet && dotnet restore && cd ..
```

If `pnpm install` complains about Node version, install Node 20.18.0 (`.nvmrc` matches). If `eslint-visitor-keys` fails — the root `pnpm.overrides` pins it; rerun.

## 3. Start the local services (≤ 60 s)

```bash
cp .env.example .env
docker compose up -d
docker compose ps     # postgres + redis + sqlserver should be "healthy"
```

## 4. Initialize the DB (≤ 60 s)

```bash
pnpm db:migrate       # asks for confirmation — answer yes the first time
pnpm db:seed          # creates the admin user
```

Default admin: `admin@loma-portal.local` / `ChangeMeOn-FirstLogin!2026`. Override via env vars (see [`prisma/README.md`](../../prisma/README.md)).

## 5. Run the apps (≤ 60 s to boot)

```bash
pnpm dev              # launches Angular + .NET + NestJS + worker in parallel via turbo
```

| URL                           | What it is                   |
| ----------------------------- | ---------------------------- |
| http://localhost:4200         | Angular frontend (primary)   |
| http://localhost:3000         | Next.js frontend (secondary) |
| http://localhost:5080         | .NET API (canonical)         |
| http://localhost:5080/swagger | Swagger UI                   |
| http://localhost:3001         | NestJS API                   |
| http://localhost:3001/docs    | NestJS Swagger UI            |

Open http://localhost:4200, sign in with the seeded admin, see the dashboard. **That's the Day-1 success state.**

## 6. Open in Claude Code

```bash
claude
```

Claude Code reads [`CLAUDE.md`](../../CLAUDE.md) automatically. From there you can run `/create-feature`, `/review-code`, `/db-migrate`, etc. (see [`.claude/commands/`](../../.claude/commands/)).

## What to do next (by role)

### Frontend

- Read [`apps/web-angular/README.md`](../../apps/web-angular/README.md) for the conventions.
- Read [`knowledge/patterns/angular-signals.md`](../../knowledge/patterns/angular-signals.md).
- Start with `/create-page <route>` for a small UI ticket.

### Backend

- Read [`dotnet/README.md`](../../dotnet/README.md) + [`knowledge/patterns/clean-architecture-dotnet.md`](../../knowledge/patterns/clean-architecture-dotnet.md).
- Open `dotnet/Loma.Portal.sln` in your IDE.
- Start with `/create-api <METHOD> <route> <domain>` for a small endpoint.

### Full-stack feature

- Run `/create-feature <name>` — this orchestrates DB → API → UI with the right skills + agents.

### DevOps

- Read [`platform/README.md`](../../platform/README.md) + [`docs/runbooks/`](../runbooks/).
- Check the CI pipeline files: [`.gitlab-ci.yml`](../../.gitlab-ci.yml) (primary) and [`.github/workflows/`](../../.github/workflows/) (parallel).

## Troubleshooting

| Symptom                                   | Fix                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `pnpm install` fails on Node engine check | Use Node ≥ 20.12.0 (check `.nvmrc` → 20.18.0); reinstall with nvm/fnm                             |
| `docker compose up` fails on port         | Stop the conflicting service; ports 5432/6379/1433 must be free                                   |
| Login fails with 401                      | Confirm `pnpm db:seed` ran; check `.env` `JWT_ACCESS_SECRET` is ≥ 32 chars                        |
| `dotnet build` fails on NU1902            | OpenTelemetry advisory chain — `NoWarn=NU1902` is set on Api csproj; restart with a clean restore |
| `pnpm validate` fails on format           | `pnpm format` then re-run                                                                         |
| Husky pre-commit blocks a `rm -rf`        | That's the bash-guard hook — by design                                                            |

## Day-1 success criteria checklist

- [ ] `pnpm install` succeeds
- [ ] `docker compose up -d` brings all 3 services to healthy
- [ ] `pnpm dev` runs without errors
- [ ] Claude Code loads `CLAUDE.md` cleanly
- [ ] `pnpm validate` passes
- [ ] `pnpm test` passes
- [ ] Browser shows login → dashboard with the seeded admin
- [ ] This file + `README.th.md` got you here

If any failed, the onboarding doc has a bug — open an issue.

## Where to learn more

- [`CLAUDE.md`](../../CLAUDE.md) — repo memory + conventions
- [`AGENTS.md`](../../AGENTS.md) — sub-agent roster
- [`docs/architecture/overview.md`](../architecture/overview.md) — C4 system diagram
- [`docs/decisions/`](../decisions/) — why we built it this way
- [`docs/runbooks/`](../runbooks/) — how to operate it
- [`docs/compliance/`](../compliance/) — PDPA + GDPR
