# 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/):

| Doc | What it covers |
| --- | --- |
| [product/business-requirements.md](product/business-requirements.md) | Full functional/business requirements |
| [product/database-model.md](product/database-model.md) | ~50-table SQL Server schema + ER diagrams + rationale |
| [product/payments-and-installments.md](product/payments-and-installments.md) | BNPL, escrow ledger, settlement, VAT (with sources) |
| [product/Home-Nursing-Platform-Research*.md](product/) | Market research (EN + FA) |

**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.

---

## 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) |

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.

---

## 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.** If you change how something works, update the `CLAUDE.md` that describes it
   in the same change. Stale instructions are worse than none.

---

## 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
```