hamid
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 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
|
|
```
|