# Naming

The names that are load-bearing across both projects, and the ones that are only conventions.

> Last verified: 2026-07-30 against commit `d3ec723`.

---

## The two names, and why there are two

The product and brand are **Balinyaar** (Persian: «بالین‌یار»). The server's code namespace is **`Baya*`**
— a legacy prefix from before the name settled.

| Layer | Name | Rule |
| --- | --- | --- |
| Server namespaces, projects, solution | `Baya.*` / `Baya.sln` | Keep it. **Do not rename without explicit instruction** — it touches 14 `.csproj` files, every namespace, and the solution. |
| Client package | `balinyaar-client` | — |
| Client import alias | `@/*` → `client/src/*` | Defined in `client/tsconfig.json`. Use it; don't write deep relative paths across folders. |
| User-facing copy | «بالین‌یار» / "Balinyaar" | Never `Baya`. See [client/i18n.md](../client/i18n.md) for the ZWNJ rule — it is linted. |

So `Baya.Application` is correct in C# and wrong in a UI string, and «بالین‌یار» is correct in a UI string
and would be wrong as a namespace. That is the whole split.

---

## Agent-facing docs

`CLAUDE.md` is the single source of truth at every level of the repo. `AGENTS.md` files exist only so the
convention is discoverable under that name too — they are **thin pointers**, never content. If you find
yourself writing a rule into an `AGENTS.md`, it belongs in the `CLAUDE.md` beside it.

Three `AGENTS.md` files exist: repo root, `client/`, `server/`.

---

## Server naming

Full C# conventions in [server/conventions.md](../server/conventions.md). The names that matter beyond
style:

| Kind | Convention | Example |
| --- | --- | --- |
| Command | `{Verb}{Noun}Command` | `CreateOrderCommand` |
| Query | `{Verb}{Noun}Query` | `GetUserOrdersQuery` |
| Handler | `{RequestName}Handler` | `CreateOrderCommandHandler` |
| Result DTO | `{RequestName}Result` | `CreateOrderCommandResult` |
| Feature folder | `Features/<Area>/{Commands\|Queries}/<VerbNoun>/` | `Features/Payments/Commands/InitiatePayment/` |
| EF config folder | `Persistence/Configuration/<Area>Config/` | `PaymentsConfig/` |
| Seam interface | `I{Capability}` in `Application/Contracts/` | `IBankTransferProvider` |
| Real adapter | `{Vendor}{Capability}` in `Seams/Real/` | `JibitBankTransferProvider` |
| Mock adapter | `Mock{Capability}` in `Seams/` | `MockBankTransferProvider` |

**Controller and action names become URLs.** All URL segments are `snake_case`, produced automatically
from `[controller]`/`[action]` tokens by `SnakeCaseParameterTransformer`. So `GetBySlug` becomes
`get_by_slug`. If a method name doesn't read cleanly as a URL, **rename the method** — never hardcode the
route string, which bypasses the transformer.

One type per file, and the file name matches the type name exactly.

---

## Client naming

| Kind | Convention | Example |
| --- | --- | --- |
| Shared component | `src/components/<Name>/<Name>.tsx` + `index.tsx` barrel | `components/TrustBadge/TrustBadge.tsx` |
| Its test | co-located `<Name>.test.tsx` | `components/TrustBadge/TrustBadge.test.tsx` |
| Page body | `<PageName>Screen.tsx`, co-located with `page.tsx` | `HomeScreen.tsx`, `SearchScreen.tsx` |
| Private (non-route) folder under `app/` | `_`-prefixed | `_chrome/`, `_hub/` |
| Route group (adds no URL segment) | parenthesised | `(customer)`, `(public-routes)` |
| Service domain | `src/services/{domain}/` | `services/bookingRequests/` |
| Query hook | one per file, `hooks/use{Action}.ts` | `hooks/useBookingDetail.ts` |
| Icon registry key | **lowercase**, semantic | `icon="verification"`, not `icon="ShieldCheck"` |
| i18n namespace | a top-level key in both message files | `booking`, `payouts` |
| Constant | `SCREAMING_SNAKE` in a `constants.ts` | `APP_FRAME_MAX_WIDTH` |

`bookings` and `bookingRequests` are **siblings, not a rename** — a booking request is the money-free
pre-payment intent, a booking exists only after capture. The same distinction is load-bearing in Persian
copy («درخواست رزرو» vs «رزرو») and in the server's singular `Booking` vs plural `Bookings` feature areas.

---

## Directory conventions that carry meaning

| Path | Meaning |
| --- | --- |
| `client/src/components/common/` | Foundational primitives, imported via `@/components` |
| `client/src/components/<domain>/` | Domain composites (`booking/`, `messaging/`, `admin/`, `geography/`, `notifications/`, `settings/`, `auth/`) |
| `client/src/services/{domain}/apis/` | The seam: `clientApi.ts` (real), `mockApi.ts`, `serverApi.ts`, `index.ts` (selects) |
| `server/src/Core/` | Domain + Application — no outward dependencies |
| `server/src/Infrastructure/` | Implementations of Application contracts |
| `server/src/API/` | Controllers, framework, plugins |
| `dev/` | The finished build-plan chain. History, not a project — nothing to build in it |
| `product/` | Business truth. Markdown canonical, HTML generated |