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

1. Project Overview
2. Solution Structure
3. Folder-by-Folder Explanation
4. Blazor and .NET 9 Features
5. Authentication & Authorization
6. Data Transfer: DTOs and Models
7. Request/Response and Data Flow
8. Key Components and Services
9. Getting Started
10. 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

1. User interacts with a Blazor UI form.
2. Page calls a service like DepartmentService.Add(departmentDto).
3. Service sends an HTTP POST request to an API endpoint.
4. Server receives DTO, maps to model, and processes it using EF Core.
5. Server returns a response DTO.
6. 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

1. Open the solution in Visual Studio 2022 or later.
2. Restore NuGet packages.
3. Build the solution.
4. Run the project (F5).
5. Explore the client UI and test login, CRUD features.

Learning Resources

• Blazor Documentation
• MudBlazor Docs
• Entity Framework Core Docs
• FastEndpoints Docs

Summary Table

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.