# Balinyaar — Repository Guide (root)

This is the **shared, repo-wide** guide for AI coding agents. It is intentionally short.
Everything specific to one side of the stack lives in that project's own `CLAUDE.md`.

> **Read the guide for the side you are editing — and only that one.**
> Working in `client/`? Read [client/CLAUDE.md](client/CLAUDE.md).
> Working in `server/`? Read [server/CLAUDE.md](server/CLAUDE.md) (+ [server/CONVENTIONS.md](server/CONVENTIONS.md)).
> You almost never need both. A frontend change does not touch server files, and vice-versa.

> `AGENTS.md` files in this repo are thin pointers to the `CLAUDE.md` in the same folder.
> `CLAUDE.md` is the single source of truth at every level.

---

## What Balinyaar is

Balinyaar is a **trust-first home-nursing marketplace in Iran**. Independent nurses (and
nursing-company employees) list configurable services; families search, book, pay, and review.
The platform holds funds in an escrow-style ledger and pays nurses out weekly after a confirmed
check-out.

Product/domain knowledge — business rules, the database model, payments/BNPL, escrow, the
verification pipeline — is **not** in the code. It lives in [`product/`](product/), organized as a
**structured docs tree** (one topic per file; start at [product/index.md](product/index.md) or its
[README](product/README.md)):

| Folder | What it covers |
| --- | --- |
| [product/overview/](product/overview/platform-summary.md) | What Balinyaar is, the four cross-cutting ground truths, Persian glossary. **Read first.** |
| [product/business/](product/business/index.md) | The 14 functional/business requirement areas, one file each |
| [product/data-model/](product/data-model/index.md) | The ~54-table SQL Server schema across 13 domains + [diagrams](product/data-model/diagrams.md) |
| [product/payments/](product/payments/index.md) | BNPL, escrow ledger, settlement, VAT, integrations (with sources) |
| [product/research/](product/research/index.md) | Market/legal/verification research & go-to-market (EN) |
| [product/notes/](product/notes/open-questions.md) | Living notes: open questions, future ideas |
| [product/fa/](product/fa/index.html) | Farsi versions (research report + verification flow) |

**Read the relevant `product/` doc before designing any schema, API, or feature.** Don't infer
business rules from code — the code is young and the docs are the source of truth.

> **Docs format:** the `.md` files are canonical; matching `.html` files are a generated, cross-linked
> browsing view (`cd product && node build-docs.mjs`). Edit the Markdown and regenerate — never
> hand-edit the `.html`. If you add/rename a `.md`, update the `NAV` manifest in `product/build-docs.mjs`.

---

## Repository layout

This is **two independent projects in one repo**. There is no root-level build, package, or
solution — each project is built, linted, and run on its own.

| Path | Project | Stack | Guide |
| --- | --- | --- | --- |
| [`client/`](client/) | Web frontend | Next.js 16 (App Router) · React 19 · TypeScript · MUI v9 · next-intl | [client/CLAUDE.md](client/CLAUDE.md) |
| [`server/`](server/) | Backend API | ASP.NET Core (.NET 10) · Clean Architecture · CQRS · EF Core | [server/CLAUDE.md](server/CLAUDE.md) |
| [`product/`](product/) | Product docs | Markdown | — (see table above) |
| [`dev/`](dev/) | Build plan (not app code) | Markdown | [dev/README.md](dev/README.md) |

The two communicate over **HTTP/JSON** (optionally gRPC). The client reads the API base URL from
`NEXT_PUBLIC_API_URL`; the server listens on `https://localhost:5002` by default.

[`dev/`](dev/README.md) holds the **phased build plan** that takes the repo from its current baseline to
the MVP: a chain of agent-runnable prompt files split into a `backend/` and a `frontend/` track
([dev/phases/](dev/phases/README.md)), the cross-project API [`contracts/`](dev/contracts/README.md), and
a [`shared-working-context/`](dev/shared-working-context/README.md) that lets a backend agent and a
frontend agent run in parallel without touching the same files. It is planning/tooling, **not** a third
project — there is nothing to build in it.

---

## Working agreements (apply to both projects)

1. **Stay within one project per change** unless the task explicitly spans both.
2. **Match the surrounding style.** Mirror existing patterns; don't introduce new ones. Each
   project documents its conventions in its own `CLAUDE.md`.
3. **Run that project's own checks before declaring work done:**
   - client: `npm run check` (type + lint), plus `npm run test:ci` if you touched a tested component.
   - server: `dotnet build Baya.sln` and `dotnet test Baya.sln`.
4. **Read the product docs before changing behavior.** Business rules are decisions, not guesses.
5. **Don't reintroduce template/starter scaffolding.** Both projects were derived from open-source
   starters; their branding, demo/showcase pages, and `_TITLE_`/`_DESCRIPTION_` placeholders were
   intentionally removed. Don't add them back.
6. **Never commit secrets.** Use `.env` (client) and `appsettings.*.json` / user-secrets (server).
   Real connection strings, keys, and tokens never enter git.
7. **Keep docs honest, and keep the architecture map current.** If you change how something works,
   update the `CLAUDE.md` that describes it in the same change. Each level documents its architecture
   in one canonical place — **this file's "Repository layout"** (repo), **client/CLAUDE.md "Project
   Structure"** (frontend), **server/CLAUDE.md "Project map"** (backend). When a change alters that
   structure — adds, removes, or renames a project, layer, route group, provider, or major folder, or
   changes a cross-project / cross-layer boundary — update the matching architecture section in the
   same change. Stale instructions are worse than none.
8. **Write clean, self-documenting code.**
   - **No dead code.** Remove unused variables, imports/usings, parameters, and private members —
     don't leave them behind and don't suppress the warning. The client enforces this with ESLint
     (`@typescript-eslint/no-unused-vars` as an *error*); on the server they are build warnings and
     the gate is zero new warnings. Per-project specifics live in each project's `CLAUDE.md` /
     `CONVENTIONS.md`.
   - **Comment the *why*, not the *what*.** Don't write verbose comments that restate what the code
     already says. Add a comment only where a non-obvious decision, constraint, business rule, or
     trade-off isn't evident from the code itself. Prefer a clearer name over a comment.

---

## Naming

- The **server**'s C# namespaces, projects, and solution all use the `Baya*` prefix
  (`Baya.Web.Api`, `Baya.sln`). Keep new server code under the `Baya.*` convention.
- The **client** package is `balinyaar-client`; the `@/*` import alias maps to `client/src/*`.

The product/brand name is **Balinyaar**; the server's `Baya*` prefix is a legacy code namespace —
do not rename it without explicit instruction.

---

## Quick start

```bash
# Frontend
cd client && npm install && npm run dev      # http://localhost:3000

# Backend
cd server && dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj   # https://localhost:5002/swagger
```