AjStarter WebApp – Full Project Documentation
This documentation provides a comprehensive overview of the AjStarter WebApp solution, including its structure, data flow, authentication, and Blazor-specific features. It is designed to help beginner developers onboard and contribute efficiently.
Table of Contents
- Project Overview
- Solution Structure
- Folder-by-Folder Explanation
- Blazor and .NET 9 Features
- Authentication & Authorization
- Data Transfer: DTOs and Models
- Request/Response and Data Flow
- Key Components and Services
- Getting Started
- Learning Resources
Project Overview
AjStarter WebApp is a modern, modular web application built using Blazor WebAssembly and .NET 9. It features a clean architecture, built-in authentication and authorization, and a rich UI powered by MudBlazor. Backend logic is handled using FastEndpoints, and database operations are managed using Entity Framework Core.
Solution Structure
AjStarter.WebApp/
├── AjStarter.WebApp/ # Server-side project (API, DB)
│ ├── Models/ # Entity models
│ ├── Migrations/ # EF Core migrations
│ └── ... # Endpoints, Data context, Config
└── AjStarter.WebApp.Client/ # Blazor WebAssembly client
├── Layout/ # UI layout components
├── Shared/ # DTOs and helpers
├── Services/ # Client-side service logic
├── Pages/ # Blazor UI pages
└── Components/ # Reusable UI components
Folder-by-Folder Explanation
Server Project: AjStarter.WebApp
Models/
- Contains database entities (e.g.,
Department.cs
) used by EF Core.
Migrations/
- Stores schema changes and database seed logic.
Endpoints/
- Handles API logic via FastEndpoints.
- Maps DTOs to models and returns responses.
Data/
- Contains the
DbContext
and related configuration.
Client Project: AjStarter.WebApp.Client
Layout/
- Layout components like
MainLayout.razor
that define UI shell and navigation.
Shared/
- DTOs and shared helpers.
- Example:
RoleDto.cs
contains data contracts for role operations.
Services/
- Service classes making HTTP requests to server APIs using
HttpClient
.
- Example:
AuthService.cs
, DepartmentService.cs
.
Pages/
- UI pages such as
Login.razor
, DepartmentList.razor
.
Components/
- Reusable UI elements like
ConfirmDialog.razor
.
Blazor and .NET 9 Features
- Blazor WebAssembly for interactive client-side execution.
- MudBlazor component library for rich UI/UX.
- .NET 9 for latest performance and framework improvements.
- FastEndpoints for minimal, high-performance APIs.
- Prerendering support for improved performance.
- Render Modes to switch between WebAssembly and Server rendering as needed.
Authentication & Authorization
Authentication
- Based on JWT tokens and ASP.NET Core Identity.
Authorization
- Role and permission-based access control.
- Uses
<AuthorizeView>
to conditionally render UI.
Admin UI for Management
- Assign roles and permissions via UI dialogs and tables.
Data Transfer: DTOs and Models
- Models: Represent entities stored in the database.
- DTOs: Used to exchange data between client and server without exposing internal models.
Example:
public class ApplicationRoleCreateDto {
public string Name { get; set; } = string.Empty;
public string Description { get; set; } = string.Empty;
public bool IsActive { get; set; } = true;
}
Request/Response and Data Flow
1. From Client to Server
- User interacts with a Blazor UI form.
- Page calls a service like
DepartmentService.Add(departmentDto)
.
- Service sends an HTTP POST request to an API endpoint.
- Server receives DTO, maps to model, and processes it using EF Core.
- Server returns a response DTO.
- UI updates accordingly.
2. Server to Database
- FastEndpoints handle requests.
- EF Core maps entities and performs operations.
- Resulting DTO is returned to the client.
3. Visual Flow
[Blazor Page]
↓ calls
[Service (HttpClient)]
↓ sends DTO
[FastEndpoint (API)]
↓ maps to Entity
[EF Core]
↓ executes CRUD
[Database]
↑ result
[FastEndpoint] → [Service] → [Blazor Page]
Key Components and Services
Layout
- MainLayout.razor: Defines top bar, drawer, and theming.
- Supports dark/light theme toggle.
- Integrates authentication state for conditional UI.
Pages
- Login.razor: Handles login UI and token management.
- DepartmentList.razor: Lists departments with edit/delete.
- RolePermissions.razor: Manage role-permission assignments.
Components
- ConfirmDialog.razor: Reusable confirmation dialog.
- AssignRolesDialog.razor: Assign roles to users.
Services
- AuthService: Handles login/logout and JWT token.
- DepartmentService: CRUD operations for departments.
- Others follow the same pattern.
Getting Started
- Open the solution in Visual Studio 2022 or later.
- Restore NuGet packages.
- Build the solution.
- Run the project (F5).
- Explore the client UI and test login, CRUD features.
Learning Resources
Summary Table
Folder |
Purpose |
Notes |
Models/ |
Entity definitions for EF Core |
Maps directly to DB tables |
Shared/Dtos/ |
Data Transfer Objects |
Used for API communication |
Services/ |
Logic for calling server APIs |
Centralized API interaction |
Layout/ |
UI layout templates |
Shell of the Blazor app |
Pages/ |
UI pages |
Uses services to perform operations |
Components/ |
Reusable UI parts |
e.g., dialogs, buttons |
Migrations/ |
Database schema and seed data |
Generated via EF Core migrations |
This guide helps developers understand the AjStarter WebApp architecture, data flow, and development practices. For any enhancements or contributions, refer to this structure and use the official documentation as a reference.