Freman.Sample.Web/docs/ai/AI_CONTEXT.md

AI_CONTEXT.md

This repository is a Blazor sample that demonstrates a real-world “browser UI calls server API” architecture with PostgreSQL.

Solution layout

• Freman.Sample.Web (Server / Host)
  • ASP.NET Core host
  • EF Core + PostgreSQL
  • Minimal API endpoints under /api/*
  • Applies migrations automatically in Development
• Freman.Sample.Web.Client (Client / Browser)
  • Blazor WebAssembly UI
  • Uses HttpClient to call server endpoints
  • /notes page is WASM interactive with prerender: false
  • Reusable UI components live under Client/Components (e.g., ConfirmModal.razor)
• Freman.Sample.Web.Contracts (Shared)
  • DTOs + request models shared between server and client
  • Examples: NoteDto, CreateNoteRequest

Run modes (important)

This solution uses mixed render modes.

• Client pages that inject HttpClient should run in the browser:
  • @rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
• Server-only pages can use:
  • @rendermode InteractiveServer

Why prerender: false?

• Without it, the component may be instantiated on the server during prerender, where client-only DI services (like the WASM HttpClient) are not available.

How to run (happy path)

• Create .env next to compose.yaml:
  • POSTGRES_PASSWORD=...
• Run:
  • docker compose up --build
• Navigate to:
  • /notes

API

• GET /api/notes
• POST /api/notes
• DELETE /api/notes/{id}

Data access

• EF Core DbContext: AppDbContext (server)
• Entities are server-only (do not share with Client)
• Contracts are shared via Freman.Sample.Web.Contracts

Conventions

• Server endpoints live in Freman.Sample.Web/Endpoints/* and are mapped from Program.cs
• Prefer small, feature-scoped endpoint files (e.g., NotesEndpoints.cs)
• Avoid duplicating DTOs in Client; use Freman.Sample.Web.Contracts instead