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. Working in server/? Read server/CLAUDE.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/:

Doc	What it covers
product/business-requirements.md	Full functional/business requirements
product/database-model.md	~50-table SQL Server schema + ER diagrams + rationale
product/payments-and-installments.md	BNPL, escrow ledger, settlement, VAT (with sources)
product/Home-Nursing-Platform-Research*.md	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/`	Web frontend	Next.js 16 (App Router) · React 19 · TypeScript · MUI v9 · next-intl	client/CLAUDE.md
`server/`	Backend API	ASP.NET Core (.NET 10) · Clean Architecture · CQRS · EF Core	server/CLAUDE.md
`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)

Stay within one project per change unless the task explicitly spans both.
Match the surrounding style. Mirror existing patterns; don't introduce new ones. Each project documents its conventions in its own CLAUDE.md.
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.
Read the product docs before changing behavior. Business rules are decisions, not guesses.
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.
Never commit secrets. Use .env (client) and appsettings.*.json / user-secrets (server). Real connection strings, keys, and tokens never enter git.
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.
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

# 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

5.7 KiB Raw Blame History