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.

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.

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.

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.

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).

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.