---
project_name: 'Campaign_Tracker App'
user_name: 'Daniel'
date: '2026-05-07'
sections_completed: ['discovery', 'technology_stack', 'language_specific_rules', 'framework_specific_rules', 'testing_rules', 'code_quality_style_rules', 'development_workflow_rules', 'critical_dont_miss_rules']
existing_patterns_found: 16
status: 'complete'
rule_count: 78
optimized_for_llm: true
---

# Project Context for AI Agents

_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._

---

## Technology Stack & Versions

- Backend is ASP.NET Core on .NET 10 with nullable reference types and implicit usings enabled.
- Backend and frontend are separate applications in one repo: `Campaign_Tracker.Server/` and `campaign-tracker-client/`.
- Backend authentication uses JWT Bearer with Keycloak/OIDC integration; agents must reuse existing auth options, role normalization, and authorization policies.
- Server-side RBAC is mandatory. Frontend permission checks are UX only and must not replace backend `[Authorize]` policies.
- Legacy Access integration uses `System.Data.OleDb`; live OleDb access is Windows-only.
- Legacy Access tables are immutable. New behavior belongs in extension-layer models/repositories and read models.
- Development can use in-memory/test data access when legacy connection config is absent; non-development must require explicit legacy configuration and must not silently fall back.
- Frontend is React 19 + TypeScript 6 + Vite 8.
- UI implementation uses Ant Design 5 and `@ant-design/icons`.
- Frontend app code should call relative `/api/...` URLs; Vite proxies `/api` to `https://localhost:7244` in development.
- Do not hard-code localhost API origins in React app code.
- Do not start duplicate backend processes on port `7244`; stop the existing server or use the configured launch profile.
- Keep React component modules separate from shared helper/contract modules when exports would violate `react-refresh/only-export-components`.
- Frontend tests live under `src`, so test files must also satisfy TypeScript build constraints.
- Backend tests use xUnit plus ASP.NET Core integration testing via `WebApplicationFactory`.
- Frontend tests use Vitest; production validation uses `tsc -b && vite build`.
- Standard validation commands are `dotnet test campaign-tracker.sln`, `npm test`, `npm run lint`, and `npm run build`.
- Vite's current large-chunk build warning is known and non-blocking unless a story specifically requires bundle optimization.

## Critical Implementation Rules

### Language-Specific Rules

- C# code uses nullable reference types; do not suppress nullability warnings casually. Model optional data explicitly with nullable types.
- Prefer immutable record types for DTOs, read models, and value-style domain data, matching existing controller/read-model patterns.
- Async repository/controller APIs should accept and pass through `CancellationToken` where existing patterns do.
- Keep backend errors explicit: return typed validation/problem responses or appropriate HTTP status codes instead of throwing for expected user/data validation cases.
- TypeScript uses strict build settings with `noUnusedLocals`, `noUnusedParameters`, `verbatimModuleSyntax`, and bundler module resolution.
- Use `import type` for type-only imports when needed by TypeScript/ESLint.
- Frontend contract modules should own API DTO types, fetch helpers, validation error classes, and pure helpers.
- React component files should export components only when React Fast Refresh lint rules would otherwise fail.
- Test files under `src` are included in TypeScript build; avoid Node-only APIs unless the test has explicit Node type support.

### Framework-Specific Rules

- Backend endpoints should be controller-based and placed under `Campaign_Tracker.Server/Controllers`.
- Protect role-specific backend endpoints with existing `ApplicationPolicy` constants; do not create one-off role string checks in controllers.
- Register backend services in `Program.cs` using existing DI patterns: singleton in-memory stores/read models for current extension-layer features unless persistence is introduced by a story.
- Legacy Access reads must go through `ILegacyDataAccess` or schema/link abstractions; do not query OleDb directly from controllers.
- React feature code should live under feature folders such as `municipalities`, `electionCycles`, `admin`, `workspace`, and `auth`.
- Workspace views should integrate through `WorkspaceShell` navigation and permission checks rather than creating separate top-level app shells.
- Use Ant Design components and tokens for workspace UI; avoid bespoke controls when Ant Design has an equivalent.
- Use `@ant-design/icons` for icon buttons/actions.
- Frontend fetch helpers should accept an optional `fetcher` parameter for tests and authenticated fetch injection.
- Authenticated frontend calls should flow through existing `authenticatedFetch` / session patterns rather than direct token handling in feature components.
- Keep Vite dev proxy assumptions localized to config and relative `/api` frontend URLs.

### Testing Rules

- Add or update backend xUnit tests for every backend behavior change; use repository/unit tests for business logic and `WebApplicationFactory` tests for endpoint/RBAC behavior.
- Integration tests should use `AuthIntegrationTestFactory` and `AuthIntegrationTestFactory.CreateToken(...)` for authenticated requests.
- Backend authorization changes must include 401/403 coverage where practical.
- Legacy compatibility changes must include tests proving legacy Access tables remain read-only or that writes occur only through extension-layer abstractions.
- Frontend API contract helpers need Vitest coverage for success and non-OK responses.
- Frontend UI/view behavior should be tested with existing lightweight patterns; do not add new browser/E2E dependencies unless the story requires them.
- For React view tests rendered with server/static markup, also test pure helper functions for keyboard/windowing logic when DOM interaction libraries are not present.
- Run focused tests red/green during implementation, then run full validation before marking BMad story tasks complete.
- Required validation before review: `dotnet test campaign-tracker.sln`, `npm test`, `npm run lint`, and `npm run build`.

### Code Quality & Style Rules

- Keep changes scoped to the active story; avoid opportunistic refactors outside the story acceptance criteria.
- Follow existing folder naming: backend feature folders are PascalCase; frontend feature folders are camelCase.
- Backend controllers and repositories should use clear domain names matching existing patterns (`Municipality...`, `ElectionCycle...`, `Legacy...`).
- Prefer small, stable DTO/read-model contracts because later stories depend on field names.
- Do not place generated build output, audit logs, temp files, `bin`, `obj`, or frontend `dist` content in story file lists.
- Use concise comments only for non-obvious domain or integration rules, especially legacy/extension boundary decisions.
- Frontend CSS should use existing workspace variables/tokens where available.
- Avoid new UI palettes or decorative styling that conflicts with the Ant Design workspace foundation.
- Keep React component text compact and operational; this is a dense internal line-of-business workspace, not a marketing page.
- Maintain accessible focus styles for keyboard-operable workspace controls.
- Do not silence ESLint or TypeScript errors unless the story explicitly requires an exception and the reason is documented.

### Development Workflow Rules

- BMad story implementation must update only permitted story sections: task checkboxes, Dev Agent Record, File List, Change Log, and Status.
- Do not mark story tasks complete until implementation exists, related tests pass, and acceptance criteria are satisfied.
- Keep `_bmad-output/implementation-artifacts/sprint-status.yaml` in sync when moving a story from `ready-for-dev` to `in-progress` to `review`.
- When adding files, update the story File List with source/test/config files that changed, not generated artifacts.
- Before running or starting local servers, check whether required ports are already in use.
- Vite dev normally uses `5173`; backend HTTPS profile uses `7244` and HTTP uses `5254`.
- If port `7244` is in use, do not start a duplicate backend; stop the existing `Campaign_Tracker.Server` process or use a different launch profile intentionally.
- Use focused tests while developing, then run full backend/frontend validations before setting a story to `review`.
- Preserve user or prior-agent changes in the worktree; do not revert unrelated edits.

### Critical Don't-Miss Rules

- Never mutate original legacy Access schema or tables. All new operational data belongs in extension-layer storage and is joined back to legacy data by stable keys.
- Treat `JCode` / `JurisCode`, `ID`, and `KitID` as critical deterministic join keys; do not normalize them in ways that break legacy joins.
- Do not bypass `LegacyLinkValidator`, legacy schema compatibility checks, or link integrity services when adding extension records tied to legacy data.
- Do not move Story 2.2+ behavior into Story 2.1-style route stubs; respect story boundaries and acceptance criteria.
- Do not trust frontend permissions as security. Backend policies must enforce role access.
- Do not create new auth, audit, or RBAC mechanisms when existing infrastructure already exists.
- Do not directly couple React views to raw backend implementation details; keep stable frontend contract helpers.
- Do not assume all municipalities have active cycle jobs, contacts, addresses, or prior-cycle defaults; empty states are required.
- Do not remove keyboard access or visible focus indicators from workspace controls.
- Do not ignore production environment differences: live OleDb requires Windows and explicit legacy configuration.
- Do not treat known Vite large-chunk warnings as a failure unless bundle optimization is in scope.

---

## Usage Guidelines

**For AI Agents:**

- Read this file before implementing any code.
- Follow all rules as documented.
- When in doubt, prefer the more restrictive option.
- Update this file if new project patterns emerge.

**For Humans:**

- Keep this file lean and focused on agent needs.
- Update it when the technology stack or implementation patterns change.
- Review periodically for outdated rules.
- Remove rules that become obvious or no longer prevent mistakes.

Last Updated: 2026-05-07