# Repository Guidelines

## Project Structure & Module Organization

`TIKU-BACKEND.slnx` is a .NET 10 modular monolith. `Tiku.Domain` holds entities; `Tiku.Application` defines use-case contracts; `Tiku.Infrastructure` contains EF Core, PostgreSQL, Redis, authentication, jobs, and external integrations. `Tiku.Api` and `Tiku.Worker` are independent runtimes; `Tiku.DbMigrator` owns migration and bootstrap work. Tests live in `Tiku.UnitTests` and `Tiku.IntegrationTests`. The React/TypeScript admin UI is in `Tiku.PlatformAdmin.Web`; documentation and deployment assets live under `docs/` and `deploy/`.

Keep dependencies flowing `Domain <- Application <- Infrastructure`. Database access, SDK integrations, and secret handling belong in Infrastructure, not controllers or domain types.

## Build, Test, and Development Commands

- `dotnet restore TIKU-BACKEND.slnx` — restore centrally managed NuGet packages.
- `dotnet build TIKU-BACKEND.slnx --no-restore` — compile the complete solution.
- `ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator` — migrate and seed the local PostgreSQL database.
- `dotnet run --project Tiku.Api` / `dotnet run --project Tiku.Worker` — start the API or background processor.
- `dotnet test TIKU-BACKEND.slnx --no-build` — run all xUnit tests.
- `dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore` — enforce C# formatting.
- `npm --prefix Tiku.PlatformAdmin.Web run check` — type-check, build, and run Vitest tests.

## Coding Style & Naming Conventions

Use four-space indentation in C# and two spaces in TypeScript. Nullable reference types and implicit usings are enabled. Use PascalCase for public C# symbols, camelCase for locals, and `Async` for asynchronous methods. Prefer feature-oriented folders and focused services. Run `dotnet format` and `git diff --check` before review. Refresh generated OpenAPI clients with `npm --prefix Tiku.PlatformAdmin.Web run generate:api` when contracts change.

## Testing Guidelines

Name xUnit files `*Tests.cs`; descriptive underscore-style method names are established. Name frontend tests `*.test.ts`. Add unit tests for isolated rules and real PostgreSQL integration tests for migrations, transactions, constraints, authorization, and tenant isolation; EF InMemory is insufficient for PostgreSQL behavior. No fixed coverage threshold is configured, but every behavior change should include regression coverage.

## Commit & Pull Request Guidelines

History follows Conventional Commits, for example `feat(learning): ...`, `fix(auth): ...`, and `docs: ...`. Keep commits scoped and exclude secrets, build output, and unrelated generated files. Pull requests should explain intent and risk, link the issue, list executed validation, call out migrations or configuration changes, and include screenshots for UI changes.

## Security & Configuration

Never commit connection strings, passwords, tokens, or production keys. Use environment variables such as `ConnectionStrings__Database`. API startup does not apply migrations; run `Tiku.DbMigrator` explicitly. Preserve Host-based tenant resolution and fail-closed authorization behavior when changing middleware or caching.