# Humand Main API

## Agent Coding Principles

**1. Think Before Coding — Don't assume. Don't hide confusion. Surface tradeoffs.**
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

**2. Simplicity First — Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- Ask: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

**3. Surgical Changes — Touch only what you must. Clean up only your own mess.**
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken. Match existing style.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that *your* changes made unused, not pre-existing ones.
- Every changed line should trace directly to the user's request.

**4. Goal-Driven Execution — Define success criteria. Loop until verified.**
- Transform tasks into verifiable goals:
  - "Fix the bug" → "Write a test that reproduces it, then make it pass"
  - "Add validation" → "Write tests for invalid inputs, then make them pass"
- For multi-step tasks, state a brief plan with a verify step per item.
- Weak criteria ("make it work") require constant clarification — define what done looks like.

---

## Project-Specific Guidelines

### Monorepo Structure

TypeScript monorepo managed with pnpm 10 workspaces + Nx 20.7, running on Node 22.12.

```
humand-packages/
├── monolith/           # Main API — Express.js, Sequelize, PostgreSQL, gRPC
│   ├── infrastructure/ # Terraform IaC, Docker, CI/CD
│   └── src/api/
│       ├── modules/    # ~66 domain modules (each has its own Nx project.json)
│       └── .shared/    # monolith-shared Nx pseudo-project
├── common/             # Shared base classes, errors, types, ports, middlewares
├── migrations-runner/  # Sequelize database migrations (~1395 migrations)
├── app-ratings/        # App ratings domain (extracted from monolith)
├── scheduled-actions/      # Scheduled actions domain (extracted from monolith)
├── community-features/     # Community features domain (extracted from monolith)
└── linter/                 # Shared ESLint configuration
```

#### Nx Project Layout

The workspace has ~70 Nx projects: 3 packages (`monolith`, `common`, `migrations-runner`) + ~66 auto-generated module-level projects (`module-{name}`) + `monolith-shared` + `integration-learnings`. Module projects are lightweight (no targets) — they exist solely for `nx affected` dependency analysis. See `docs/adr/001-affected-test-strategy.md` for the full rationale.

Path aliases (defined in `tsconfig.build.json`):
- `@humand-packages/common` → `humand-packages/common/src`
- `@humand-packages/monolith` → `humand-packages/monolith/src`
- `@humand-packages/migrations-runner` → `humand-packages/migrations-runner/src`
- `@humand-packages/app-ratings` → `humand-packages/app-ratings/src`
- `@humand-packages/scheduled-actions` → `humand-packages/scheduled-actions/src`
- `@humand-packages/community-features` → `humand-packages/community-features/src`

### Key Commands

```bash
pnpm install                              # Install all dependencies
pnpm nx run monolith:build                # Build monolith
pnpm --filter monolith start-local        # Dev server with watch + debug
pnpm nx run monolith:test-all             # Unit tests (full suite)
pnpm nx run monolith:test-integration-all # Integration tests (full suite)
pnpm nx run-many --target=lint            # Lint all packages
```

#### Affected Testing Scripts

```bash
# Preview what the affected analysis would do on your branch
cd humand-packages/monolith
node --no-warnings --experimental-strip-types --experimental-detect-module scripts/validate-affected.ts

# Regenerate module dependency graph (after adding cross-module imports)
node --no-warnings --experimental-strip-types --experimental-detect-module scripts/generate-module-deps.ts

# Regenerate per-module project.json files (after changing module-deps.json)
node --no-warnings --experimental-strip-types --experimental-detect-module scripts/generate-module-projects.ts
```

### Server Node Types

The monolith runs in different modes via `NODE_TYPE` env var:

| Type | Purpose |
|------|---------|
| APP | Main application server |
| BACKOFFICE | Admin/backoffice server |
| PUBLIC | Public API server |
| GRPC | gRPC server |
| EVENT_HANDLER | SQS queue consumers |
| WORKER | Background workers |
| CDC | Change Data Capture |
| ALL | All services combined |

### Git Workflow

- **PR base branch: `develop`.** Feature branches merge back to `develop`; `master` is not the day-to-day PR target despite git's `origin/HEAD` pointing to it. Use `develop` when opening PRs, running `git merge-base`, or picking a branch-off point.

### Module Dependencies & Affected Testing

CI uses `nx affected` to run only tests for changed modules. The dependency graph is auto-generated from static import analysis.

**When to regenerate**: If you add a new cross-module import (module A starts importing from module B), regenerate the graph:

```bash
cd humand-packages/monolith
node --no-warnings --experimental-strip-types --experimental-detect-module scripts/generate-module-deps.ts
node --no-warnings --experimental-strip-types --experimental-detect-module scripts/generate-module-projects.ts
```

**When to verify**: After regenerating, or on any branch before pushing, run `scripts/validate-affected.ts` to preview what tests would run.

**Key rules**:
- Changes to `@humand-packages/common`, `monolith-shared` zones (`src/api/services/`, `kernels/`, `config/`, `ormModels/`, `routes/`, `diHandlers/`, `apiConfig/`), or `migrations-runner` trigger ALL tests.
- Changes within `src/api/modules/{name}/` trigger only that module + its dependents.
- `module-deps.json` and per-module `project.json` files are committed. Keep them in sync.

### Keeping AGENTS.md Up to Date

After any non-trivial change to a module or package, check whether the corresponding `AGENTS.md` needs updating. Non-trivial changes include:

- Adding or removing files (new services, ports, adapters, controllers, DAOs, mappers, VCs, SCs)
- Adding or removing endpoints
- Changing a service's responsibilities or the flow between layers
- Adding new integration test files or command files
- Changing architectural decisions (new patterns, new gotchas, new invariants)

Simple changes that do NOT require an AGENTS.md update: bug fixes that don't change structure, renaming internals without changing the public shape, updating values inside existing logic.

**Rule:** if the `AGENTS.md` would mislead an agent reading it cold after your change, update it.

### File Conventions

Whenever you create or modify an `AGENTS.md` in any directory, verify that a `CLAUDE.md` symlink exists alongside it pointing to it. If not, create it:

```bash
ln -s AGENTS.md CLAUDE.md
```

**Why:** `.claude` is a symlink to `.cursor`, so Claude Code reads `CLAUDE.md` files. Without the symlink, Claude Code ignores the agent rules in that directory.

Whenever you **add a new `AGENTS.md`** to any directory, also update the **Agent Context Map** section in the root `AGENTS.md` with the new entry.

### Agent Context Map

Each package and some modules have their own `AGENTS.md` (with a `CLAUDE.md` symlink) containing package-specific rules. Read the relevant file before touching code in that directory.

| Path | Covers |
|------|--------|
| `humand-packages/monolith/AGENTS.md` | Express/Sequelize patterns, hexagonal vs legacy architecture, DI, testing |
| `humand-packages/monolith/infrastructure/AGENTS.md` | Terraform IaC, Docker, CI/CD, AWS ECS Fargate |
| `humand-packages/common/AGENTS.md` | Shared base classes, errors, types, ports, middlewares — extraction rules |
| `humand-packages/migrations-runner/AGENTS.md` | Sequelize migration conventions (~1395 migrations) |
| `humand-packages/app-ratings/AGENTS.md` | App ratings extracted domain |
| `humand-packages/scheduled-actions/AGENTS.md` | Scheduled actions extracted domain |
| `humand-packages/linter/AGENTS.md` | Shared ESLint 9 flat config |
| `humand-packages/monolith/src/api/modules/timeOff/AGENTS.md` | TimeOff module (~337 files, legacy DB names) |
| `humand-packages/monolith/src/api/modules/recognitions/AGENTS.md` | Recognitions module (products, categories, multi-tenant) |
| `humand-packages/monolith/src/api/modules/auth/AGENTS.md` | Auth module — login, SSO, SAML IdP, OTP, 2FA, API keys, bot-app auth, session management, JWT middleware |
| `humand-packages/monolith/src/api/modules/groups/AGENTS.md` | Groups module — 9 focused services, hexagonal architecture, membership, posts, notifications |
| `humand-packages/monolith/src/api/modules/goals/AGENTS.md` | Goals module — cycles, goals, progress pipeline, weights, formula chains; per-instance vs per-cycle config (incl. maxProgressPercent cap) |
| `humand-packages/monolith/src/api/modules/learningCertificates/AGENTS.md` | LearningCertificates module — certificate template management, file asset lifecycle, hexagonal architecture |
| `humand-packages/monolith/src/api/modules/timeTracking/AGENTS.md` | TimeTracking module (~408 files) — entries, day summaries, work schedules, shifts, kiosks, policies, hour categorization |
| `humand-packages/monolith/src/api/modules/aiAgent/AGENTS.md` | AI Agent module — BFF for Meeseeks (Sammy 2.0). Stateless proxy, no DAOs, agent resolution by name with in-memory cache |
| `humand-packages/monolith/src/api/modules/performanceReviews/AGENTS.md` | PerformanceReviews module — cycles, form templates, reviewers, fill, scoring, nine-box, calibration (rules, atomic claim, subordinate snapshot), external reviewers |
| `humand-packages/monolith/src/api/modules/posts/AGENTS.md` | Posts module — published-feed listing modes (segmentation / composed / legacy) and the signature-keyed feed-visibility cache (Plan A) |
| `humand-packages/monolith/src/api/kernels/dynamicForms/AGENTS.md` | DynamicForms kernel — form versioning, answer progression engine, PDF forms, certificates, gRPC surface |
| `humand-packages/monolith/test-integration/AGENTS.md` | Integration test framework — sessions, commands, mocks, utils, isolation rules |