37 lines
3.2 KiB
Markdown
37 lines
3.2 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `FictionArchive.sln` ties together the gateway and all subgraph services.
|
|
- `FictionArchive.API`: Fusion gateway host; GraphQL endpoint at `/graphql`, health at `/healthz`, gateway configuration in `gateway.fgp`, and helper script `build_gateway.py`.
|
|
- `FictionArchive.Service.*`: GraphQL subgraphs (`AuthenticationService`, `FileService`, `NovelService`, `SchedulerService`, `TranslationService`, `UserService`) plus shared helpers in `FictionArchive.Service.Shared`.
|
|
- `FictionArchive.Common`: shared enums and hosting extensions used across services.
|
|
- Environment/config files live beside each service (`appsettings*.json`, `Properties/launchSettings.json`); build outputs under `bin/` and `obj/` should stay untracked.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `dotnet restore` then `dotnet build FictionArchive.sln` (Debug by default) to validate all projects compile.
|
|
- Run the gateway: `dotnet run --project FictionArchive.API` (serves HTTPS; ensure certificates are trusted locally).
|
|
- Run a subgraph locally: `dotnet run --project FictionArchive.Service.NovelService` (or any other service) to debug a single domain.
|
|
- Rebuild the Fusion gateway config after subgraph changes: `python FictionArchive.API/build_gateway.py` (requires Python 3 and the `fusion` CLI on PATH; uses `gateway_skip.txt` to omit services).
|
|
- If tests are added, prefer `dotnet test FictionArchive.sln` to cover the whole solution.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Target .NET 8/C# 12; use 4-space indentation and file-scoped namespaces where practical.
|
|
- PascalCase for classes, records, interfaces, and public members; camelCase for locals/parameters; suffix async methods with `Async`.
|
|
- Favor dependency injection and extension methods for service wiring (see `Program.cs` files and `FictionArchive.Service.Shared/Extensions`).
|
|
- Keep GraphQL schema files and other generated artifacts out of commits unless intentionally versioned.
|
|
|
|
## Testing Guidelines
|
|
- No dedicated test projects exist yet; when adding tests, create `*.Tests` projects aligned to each service (e.g., `FictionArchive.Service.NovelService.Tests`) and name test files `*Tests.cs`.
|
|
- Prefer xUnit with fluent assertions; aim for coverage on controllers/resolvers, integration events, and critical extension methods.
|
|
- Use in-memory fakes or test containers for external dependencies to keep tests deterministic.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Follow the observed pattern: `[FA-123] Short, imperative summary` (reference the tracker ID and keep scope focused).
|
|
- Keep commits small and self-contained; include relevant config/schema updates produced by the gateway build script when behavior changes.
|
|
- PRs should describe the problem, the solution, and any follow-up work; link to issues, attach GraphQL schema diffs or sample queries when applicable, and note any manual steps (migrations, secrets).
|
|
|
|
## Security & Configuration Tips
|
|
- Do not commit secrets; use user secrets or environment variables for API keys and connection strings referenced in `appsettings*.json`.
|
|
- Verify HTTPS is enabled locally; adjust `launchSettings.json` only when necessary and document non-default ports.
|
|
- Regenerate `gateway.fgp` after changing subgraph schemas to avoid stale compositions.
|