# almamun09/localscout_v2 architecture

> Architecture diagram of the GitHub repository almamun09/localscout_v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/almamun09/localscout_v2
- Repository: https://github.com/almamun09/localscout_v2

## Overview

1. **Overall shape**  
LocalScout is a .NET 8 ASP.NET Core MVC solution split into three clear layers: `Domain`, `Application`, and `Infrastructure`, with `Web` as the presentation host. The runtime entrypoint is `LocalScout.Web`, which wires together Identity, repositories, services, and MVC controllers/views.

2. **Domain layer: core business model**  
`LocalScout.Domain` contains the business entities and enums that define the system’s state: users, services, service categories, bookings, reviews, notifications, audit logs, verification requests, provider time slots, service blocks, and reschedule proposals. These are the canonical data objects the rest of the app revolves around.

3. **Application layer: contracts and screen-shaped DTOs**  
`LocalScout.Application` is mostly a contract and mapping layer. It defines repository/service interfaces plus DTOs for bookings, payments, reports, reviews, dashboards, notifications, verification, and search. This layer shapes data for specific use cases instead of exposing raw domain entities to the UI.

4. **Infrastructure layer: persistence and external integrations**  
`LocalScout.Infrastructure` owns EF Core persistence through `ApplicationDbContext`, entity configurations, migrations, and seeding. It also implements the repository interfaces and domain services such as scheduling, time zone handling, email, PDF receipt/report generation, AI description generation, and SSLCommerz payment integration.

5. **Presentation layer: MVC site and Identity UI**  
`LocalScout.Web` hosts the app’s controllers, Razor views, and Identity pages. The UI is organized by functional areas like Home, Service, Booking, Payment, Review, Report, Admin, Provider, and User, plus the built-in `Areas/Identity` registration/login flow. The app uses standard MVC request/response boundaries rather than APIs as the primary interface.

6. **Authentication and roles**  
ASP.NET Core Identity is central to the architecture. The system supports role-based access control with `Admin`, `ServiceProvider`, and `User`, and the registration flow is split for normal users and providers. Identity pages under `Areas/Identity` handle confirmation, password reset, login/logout, and provider-specific registration.

7. **Service marketplace flow**  
The main user journey is: browse/search services, view service details, create bookings, and track booking status. Controllers in `Service`, `Booking`, and `Home` assemble DTOs for cards, detail pages, and search results, while the repository layer persists service listings, provider relationships, and availability data.

8. **Booking, rescheduling, and payments**  
Booking is a multi-stage workflow with provider acceptance/decline, proposed time adjustments, cancellation, and completion. Payment is separated into its own module and uses SSLCommerz plus receipt/history DTOs. This gives the architecture a distinct transaction boundary: booking state changes happen in the app, but payment processing crosses into an external gateway and then back into persisted history/receipt records.

9. **Provider verification and category governance**  
Providers submit verification documents and category requests, which are then reviewed by admins. The repo includes verification entities, category request handling, and service category approval/inactive/active management. Uploaded verification PDFs are stored under `wwwroot/uploads`, making document handling part of the system boundary rather than pure database data.

10. **Operational concerns: notifications, audit, reports**  
Notifications are a first-class subsystem with in-app read/unread state. Audit logging tracks administrative and security-relevant actions. Reporting is split by audience: admin, provider, and user reports, with PDF generation handled in infrastructure. These are not just UI pages; they represent distinct read-model style views over the same transactional data.

11. **Location and AI integrations**  
Location features are split across a web-side JavaScript module and an infrastructure `LocationService`. The frontend handles geolocation/autocomplete behavior, while the backend integrates with LocationIQ for geocoding and proximity support. AI-assisted content generation is similarly separated behind `IAIService` and an implementation in infrastructure, using Hugging Face for generated descriptions.

12. **Front-end assets and static content**  
The web project carries substantial static UI assets: AdminLTE, Bootstrap, jQuery, DataTables, Select2, SweetAlert2, and custom JS modules for validation, notifications, multi-step forms, and location services. This means the presentation layer is not a thin shell; a significant amount of user interaction logic lives in browser-side scripts and Razor partials.

13. **Persistence boundary and migrations**  
All durable state is backed by SQL Server through EF Core migrations in `LocalScout.Infrastructure/Migrations`. The migration history shows the app evolving around booking, payment info, verification, notifications, audit logs, and service/category changes. `DbSeeder` and the role constants indicate the database is also responsible for bootstrapping platform roles and initial data.

14. **How to diagram the main dependency direction**  
The clean dependency direction is: browser/UI → MVC controllers/Razor pages → application DTOs and interfaces → infrastructure implementations → EF Core/SQL Server and external services. Domain stays isolated at the center, while the web project is the composition root and the infrastructure project is where side effects live.

Main entry points: [`LocalScout.Infrastructure/Data/ApplicationDbContext.cs`](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Data/ApplicationDbContext.cs) (Db context), [`LocalScout.Web/Controllers`](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Controllers) (Controllers), [`LocalScout.Application/Interfaces`](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/Interfaces) (Contracts), [`LocalScout.Web/Program.cs`](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Program.cs) (Web host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_web["Web host<br/>mvc host<br/>[Program.cs]"]
  node_controllers["Controllers<br/>[Controllers]"]
  node_views["Razor views<br/>ui views<br/>[Views]"]
  node_identity["Identity UI<br/>auth pages<br/>[Account]"]
  node_assets["Web assets<br/>static ui<br/>[wwwroot]"]
end

subgraph group_application["Application"]
  node_dtos["DTOs<br/>screen models<br/>[DTOs]"]
  node_contracts["Contracts<br/>interfaces<br/>[Interfaces]"]
  node_application_services["App services<br/>helpers<br/>[Services]"]
end

subgraph group_domain["Domain"]
  node_domain_entities["Entities<br/>domain model<br/>[Entities]"]
  node_domain_enums{{"Enums<br/>status model<br/>[Enums]"}}
end

subgraph group_infrastructure["Infrastructure"]
  node_dbcontext[("Db context<br/>ef core")]
  node_migrations["Migrations<br/>schema history<br/>[Migrations]"]
  node_repositories["Repositories<br/>data access<br/>[Repositories]"]
  node_infra_services["Infra services<br/>integrations<br/>[Services]"]
  node_seeder(("Db seeder<br/>bootstrap<br/>[DbSeeder.cs]"))
  node_roles{{"Role names<br/>auth constants<br/>[RoleNames.cs]"}}
end

node_web -->|"hosts"| node_controllers
node_web -->|"enables"| node_identity
node_web -->|"renders"| node_views
node_web -->|"serves"| node_assets
node_controllers -->|"uses"| node_dtos
node_controllers -->|"depends on"| node_contracts
node_controllers -->|"returns"| node_views
node_identity -->|"auth flow"| node_contracts
node_dtos -.->|"maps from"| node_domain_entities
node_contracts -->|"implemented by"| node_repositories
node_contracts -->|"implemented by"| node_infra_services
node_contracts -->|"persists via"| node_dbcontext
node_repositories -->|"uses"| node_dbcontext
node_dbcontext -->|"maps"| node_domain_entities
node_dbcontext -->|"tracks"| node_domain_enums
node_dbcontext -.->|"evolves with"| node_migrations
node_infra_services -->|"acts on"| node_domain_entities
node_seeder -->|"bootstraps"| node_roles
node_seeder -->|"writes"| node_dbcontext
node_assets -.->|"supports"| node_controllers

click node_web "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Program.cs"
click node_controllers "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Controllers"
click node_views "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Views"
click node_identity "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Areas/Identity/Pages/Account"
click node_assets "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/wwwroot"
click node_dtos "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/DTOs"
click node_contracts "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/Interfaces"
click node_application_services "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/Services"
click node_domain_entities "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Domain/Entities"
click node_domain_enums "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Domain/Enums"
click node_dbcontext "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Data/ApplicationDbContext.cs"
click node_migrations "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Migrations"
click node_repositories "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Repositories"
click node_infra_services "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Services"
click node_seeder "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Data/DbSeeder.cs"
click node_roles "https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Constants/RoleNames.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_controllers,node_views,node_identity,node_assets toneBlue
class node_dtos,node_contracts,node_application_services toneAmber
class node_domain_entities,node_domain_enums toneMint
class node_dbcontext,node_migrations,node_repositories,node_infra_services,node_seeder,node_roles toneRose
```

## Components

### Presentation

ASP.NET Core MVC host, controllers, views, and Identity UI.

- [Web host](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Program.cs): mvc host · Composition root and MVC runtime entrypoint. · `LocalScout.Web/Program.cs`
- [Controllers](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Controllers): mvc controllers · Request handlers for marketplace, admin, booking, payment, reporting, and verification flows. · `LocalScout.Web/Controllers`
- [Razor views](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Views): ui views · Server-rendered pages and partials for dashboards, forms, lists, and dialogs. · `LocalScout.Web/Views`
- [Identity UI](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/Areas/Identity/Pages/Account): auth pages · Login, registration, password reset, and account management pages. · `LocalScout.Web/Areas/Identity/Pages/Account`
- [Web assets](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Web/wwwroot): static ui · Client-side scripts, styles, and bundled UI libraries. · `LocalScout.Web/wwwroot`

### Application

DTOs, interfaces, and use-case shaping contracts.

- [DTOs](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/DTOs): screen models · Booking, payment, reporting, dashboard, search, review, and verification data shapes. · `LocalScout.Application/DTOs`
- [Contracts](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/Interfaces): interfaces · Repository and service abstractions used by the web and infrastructure layers. · `LocalScout.Application/Interfaces`
- [App services](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Application/Services): helpers · Shared application-level services and utilities such as time zone and distance logic. · `LocalScout.Application/Services`

### Domain

Core entities and enums.

- [Entities](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Domain/Entities): domain model · Users, services, bookings, reviews, notifications, audits, verification, slots, blocks, and reschedules. · `LocalScout.Domain/Entities`
- [Enums](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Domain/Enums): status model · Booking, reschedule, and verification state definitions. · `LocalScout.Domain/Enums`

### Infrastructure

EF Core persistence, repositories, and external integrations.

- [Db context](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Data/ApplicationDbContext.cs): ef core · ApplicationDbContext and model configuration for SQL Server persistence. · `LocalScout.Infrastructure/Data/ApplicationDbContext.cs`
- [Migrations](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Migrations): schema history · EF Core schema evolution and snapshot history. · `LocalScout.Infrastructure/Migrations`
- [Repositories](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Repositories): data access · EF-backed implementations for bookings, services, users, reviews, notifications, verification, and related flows. · `LocalScout.Infrastructure/Repositories`
- [Infra services](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Services): integrations · Scheduling, time zone, email, PDF, AI, location, payment, and automation services. · `LocalScout.Infrastructure/Services`
- [Db seeder](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Data/DbSeeder.cs): bootstrap · Initial role and data seeding. · `LocalScout.Infrastructure/Data/DbSeeder.cs`
- [Role names](https://github.com/almamun09/localscout_v2/blob/main/LocalScout.Infrastructure/Constants/RoleNames.cs): auth constants · Admin, ServiceProvider, and User role constants. · `LocalScout.Infrastructure/Constants/RoleNames.cs`

## Connections

- Web host → Controllers: hosts · The MVC host routes requests to controllers.
- Web host → Identity UI: enables · Identity pages are mounted into the web host.
- Web host → Razor views: renders · Controllers return Razor views and partials.
- Web host → Web assets: serves · Static scripts and styles support the UI.
- Controllers → DTOs: uses · Controllers assemble screen-shaped data for pages and workflows.
- Controllers → Contracts: depends on · Controllers call application abstractions for data and actions.
- Controllers → Razor views: returns · MVC responses are rendered with server-side views.
- Identity UI → Contracts: auth flow · Registration and account flows rely on app abstractions.
- DTOs → Entities: maps from · DTOs shape and project domain state.
- Contracts → Repositories: implemented by · Infrastructure supplies concrete repository implementations.
- Contracts → Infra services: implemented by · Infrastructure supplies external and domain service implementations.
- Contracts → Db context: persists via · Repository implementations query and save through EF Core.
- Repositories → Db context: uses · Repositories operate on the EF Core context.
- Db context → Entities: maps · The context is built around the domain entities.
- Db context → Enums: tracks · State fields are backed by domain enums.
- Db context → Migrations: evolves with · Schema changes are captured as migrations.
- Infra services → Entities: acts on · Services coordinate bookings, notifications, reports, payments, and location data.
- Db seeder → Role names: bootstraps · Initial identity roles are seeded into the database.
- Db seeder → Db context: writes · Seed data is applied through EF Core.
- Web assets → Controllers: supports · Browser-side behavior complements controller workflows.