hamid
124 lines
7.1 KiB
Markdown
124 lines
7.1 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/), 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
|
|
```
|