Architecture

Architecture Overview

System Architecture

MatchBy is built as a Blazor Server application using .NET 9, following a layered architecture pattern with clear separation of concerns.

Architecture Layers

1. Presentation Layer

• Location: MatchBy/Components/
• Technology: Blazor Server with Razor Components
• Responsibilities:
  • User interface rendering
  • User interaction handling
  • Component composition
  • Client-side state management

Key Components:

• Pages/ - Main application pages (Home, Matches, Chat, Profile)
• Layout/ - Layout components (MainLayout, Header, Footer)
• Account/ - Identity-related pages (Login, Register, etc.)

2. Business Logic Layer

• Location: MatchBy/Services/
• Responsibilities:
  • Business rule enforcement
  • Data transformation
  • Service orchestration
  • Validation coordination

Services:

• Matches/ - Match creation, search, and management
• Users/ - User profile and account management
• Conversations/ - Conversation management
• ChatMessages/ - Message handling and delivery
• Email/ - Email sending functionality
• S3/ - File storage operations
• FileValidator/ - File validation logic

3. Data Access Layer

• Location: MatchBy/Data/
• Technology: Entity Framework Core with PostgreSQL
• Responsibilities:
  • Database context management
  • Entity configurations
  • Migration management
  • Data seeding

Key Components:

• ApplicationDbContext.cs - Main database context
• Configurations/ - Entity Framework configurations
• Migrations/ - Database migrations
• Seeders/ - Database seeding logic

4. Domain Layer

• Location: MatchBy/Models/
• Responsibilities:
  • Domain entities
  • Business domain logic
  • Value objects

Core Models:

• ApplicationUser - User entity (extends IdentityUser)
• Match - Match/Game entity
• Team - Team entity
• ChatMessage - Chat message entity
• Conversation - Conversation entity
• Friend - Friend relationship
• PlayerRating - Player rating/feedback
• MatchInvite / TeamInvite - Invitation entities

5. DTOs (Data Transfer Objects)

• Location: MatchBy/DTOs/
• Responsibilities:
  • Data transfer between layers
  • API contract definition
  • Data mapping

DTO Categories:

• Match/ - Match-related DTOs
• Chat/ - Chat-related DTOs (Messages, Conversations)
• User/ - User-related DTOs

Real-time Communication

SignalR Hubs

• Location: MatchBy/Hubs/
• Technology: ASP.NET Core SignalR
• Purpose: Real-time bidirectional communication

Hubs:

• ChatHub - Real-time chat messaging

Dependency Injection

All services are registered in Program.cs using the built-in dependency injection container:

• Scoped Services: Most business services (MatchesService, UsersService, etc.)
• Singleton Services: S3Service, configuration services
• Transient Services: EmailSender

Authentication & Authorization

• Framework: ASP.NET Core Identity
• Authentication: Cookie-based authentication
• Features:
  • Email confirmation required
  • Two-factor authentication support
  • Password reset functionality
  • Account deletion

File Storage

• Service: AWS S3 (via Supabase Storage)
• Location: MatchBy/Services/S3/
• Usage: Profile images, match-related files
• Configuration: S3Settings in appsettings.json

Validation

• Framework: FluentValidation
• Location: MatchBy/Validators/
• Usage: Server-side validation for DTOs and models

Database

• Provider: PostgreSQL (via Npgsql)
• ORM: Entity Framework Core 9
• Naming: Snake_case (via EFCore.NamingConventions)
• Migrations: Code-first approach

External Services

1. Resend - Email delivery service
2. AWS S3 (Supabase Storage) - File storage
3. Sentry - Error tracking and monitoring (optional)
4. Blazorise - UI component library

Project Structure

MatchBy/
├── Components/          # Presentation layer
│   ├── Pages/          # Application pages
│   ├── Layout/         # Layout components
│   └── Account/        # Identity pages
├── Controllers/        # API controllers
├── Data/              # Data access layer
│   ├── Configurations/
│   ├── Migrations/
│   └── Seeders/
├── DTOs/              # Data transfer objects
├── Enums/             # Enumerations
├── Extensions/        # Extension methods
├── Hubs/              # SignalR hubs
├── Models/            # Domain models
├── Services/          # Business logic services
├── Settings/          # Configuration classes
└── Validators/         # FluentValidation validators

Communication Flow

1. User Request → Blazor Component
2. Component → Service (via DI)
3. Service → DbContext (via DI)
4. DbContext → PostgreSQL Database
5. Response flows back through the layers

Real-time Updates

1. Client → SignalR Hub
2. Hub → Broadcast to connected clients
3. Clients receive updates via WebSocket connection

Best Practices

• Separation of Concerns: Each layer has a single responsibility
• Dependency Injection: All dependencies injected via constructor
• Async/Await: All I/O operations are asynchronous
• Error Handling: Centralized error handling with custom error pages
• Validation: Server-side validation using FluentValidation
• Configuration: Settings stored in appsettings.json or User Secrets

Related Documentation

• Home - Main documentation index
• Database Schema - Database structure
• Deployment - Deployment and CI/CD