Campaign_Tracker/_bmad-output/implementation-artifacts/1-1-project-initialization-solution-scaffold.md

Story 1.1: Project Initialization & Solution Scaffold

Status: ready-for-dev

Story

As a developer,
I want the solution scaffolded with ASP.NET Core 10 Web API and Vite React TypeScript,
so that the team has a working, runnable baseline with the correct project structure for all subsequent stories.

Acceptance Criteria

1. Given the initialization commands are run (dotnet new sln, dotnet new webapi, npm create vite@latest --template react-ts) when the solution builds, then both BriansClientRouteReports.Server and brians-client-route-reports-client compile without errors.
2. Given the solution is running locally, when the Vite dev server starts, then the React app loads at the configured local URL with no console errors.
3. Given the server is running, when GET /health is called, then it returns 200 OK with a status payload.
4. Given the solution structure is created, when reviewed against the architecture decision, then the .sln file, server project folder, and client project folder exist at expected paths and .gitignore excludes node_modules, bin, obj, and .env files.

Tasks / Subtasks

• Create baseline solution and projects (AC: 1, 4)
  • Run dotnet new sln -n brians-client-route-reports at repo root.
  • Run dotnet new webapi -n BriansClientRouteReports.Server -f net10.0 --use-controllers.
  • Add server project to solution: dotnet sln add .\\BriansClientRouteReports.Server\\BriansClientRouteReports.Server.csproj.
  • Run npm create vite@latest brians-client-route-reports-client -- --template react-ts.
• Add operational baseline hardening files (AC: 4)
  • Add/update root .gitignore with .env, node_modules/, bin/, obj/, and common build artifacts.
  • Ensure folders are exactly:
    • ./BriansClientRouteReports.Server/
    • ./brians-client-route-reports-client/
    • ./brians-client-route-reports.sln
• Implement health endpoint (AC: 3)
  • Ensure server exposes GET /health returning JSON payload and HTTP 200.
  • Add lightweight server integration check for /health response shape and status.
• Verify local run and build paths (AC: 1, 2, 3)
  • Validate dotnet build succeeds for server and solution.
  • Validate client install and dev start (npm install, npm run dev) succeeds with no runtime console errors on first render.
  • Capture exact run commands in README or implementation notes for handoff.

Dev Notes

• This story is the implementation foundation for all subsequent stories in Epic 1.
• Do not add domain models, workflow logic, or auth integration here; keep scope to scaffold + health + runnability.
• Preserve architecture separation: independent server and client lifecycle with explicit boundary.

Technical Requirements

• Backend stack: ASP.NET Core 10 Web API (net10.0) with controllers template option enabled.
• Frontend stack: Vite + React + TypeScript (react-ts).
• Node requirement from Vite docs: Node.js 20.19+ or 22.12+.
• Must retain ability to run server/client independently in local development.

Architecture Compliance

• Use selected starter architecture exactly as documented.
• Keep immutable-legacy policy in mind: this story must not introduce data-layer assumptions that alter legacy schemas.
• Keep future role-based and UX work unblocked by maintaining clean folder and naming patterns.

File Structure Requirements

• Required outputs:
  • brians-client-route-reports.sln
  • BriansClientRouteReports.Server/BriansClientRouteReports.Server.csproj
  • brians-client-route-reports-client/package.json
• Keep server and client sibling directories at repo root.

Testing Requirements

• Minimum for this story:
  • Build verification (dotnet build and client install/run).
  • Health endpoint verification (GET /health returns 200 and JSON payload).
  • Smoke-level client render check (no console errors on first load).

Project Structure Notes

• This repository currently centers planning artifacts in _bmad-output/planning-artifacts.
• Implementation outputs for stories are stored in _bmad-output/implementation-artifacts.
• Keep story-driven changes traceable and avoid editing planning docs during implementation unless explicitly requested.

References

• Story source and ACs: _bmad-output/planning-artifacts/epics.md (Story 1.1 section)
• Starter commands and rationale: _bmad-output/planning-artifacts/architecture.md (Selected Starter section)
• UX/build context and component roadmap: _bmad-output/planning-artifacts/ux-design-specification.md (Implementation Roadmap / Component Strategy)
• Vite CLI and template usage + Node version: https://vite.dev/guide/
• .NET template behavior and options (webapi, --use-controllers, net10.0): https://learn.microsoft.com/dotnet/core/tools/dotnet-new-sdk-templates

Dev Agent Record

Agent Model Used

GPT-5 Codex

Debug Log References

• Sprint source file: _bmad-output/implementation-artifacts/sprint-status.yaml
• Requirement source files: epics.md, architecture.md, ux-design-specification.md

Completion Notes List

• Comprehensive context generated for Story 1.1 with explicit guardrails, commands, and scope boundaries.
• Story is intentionally constrained to scaffold readiness and health-check baseline.

File List

• _bmad-output/implementation-artifacts/1-1-project-initialization-solution-scaffold.md