# israel-bsi/realtyhub architecture

> Architecture diagram of the GitHub repository israel-bsi/realtyhub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/israel-bsi/realtyhub
- Repository: https://github.com/israel-bsi/realtyhub

## Overview

##### Project type and purpose
- This is a full-stack .NET real-estate management system (“RealtyHub”) built as a Blazor WebAssembly application with a separate Web API service and a shared domain library.
- Purpose: allow users to manage properties, viewings, offers, contracts, customers, condominiums and generate reports; authenticate users; send emails; store contract templates and generated documents.

##### File structure
- Top-level solution: RealtyHub.sln
- RealtyHub.Core
- Shared domain models, DTOs (Requests/Responses), enums, handler interfaces, utilities (fake data), service abstractions (IEmailService, ISearchCep).
- RealtyHub.ApiService
- Minimal-API endpoints (Endpoints/… .cs), handlers (business logic), EF Core DbContext + entity mappings, migrations, services (EmailService, ContractGenerator, ReportServices), configuration (appsettings, DI registrations), Program.cs.
- RealtyHub.AppHost
- ASP.NET Core host for the Blazor client (serves static files, configures proxy to the ApiService, authentication settings).
- RealtyHub.Web
- Blazor WebAssembly client: UI components, pages, layout, component handlers, client-side services (ViaCepService, EmailService, Report clients), security (cookie auth), wwwroot assets.
- RealtyHub.Tests
- Unit and integration tests for core handlers and API endpoints.

##### Essential details
- Shared Core project as a “package” dependency of both Web and ApiService
- Critical flows: authentication (login → token or cookie → subsequent calls), email generation, report PDF generation
- Don’t over-complicate: focus on each distinct layer and its primary responsibilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Tier
    subgraph "Presentation Tier"
        direction TB
        Browser["User Browser\n(Blazor WebAssembly)"]:::presentation
        WebApp["Blazor WebAssembly Client"]:::presentation
        CompPages["UI Components & Pages"]:::presentation
        HandlersWeb["Blazor Client Handlers"]:::presentation
        ServicesWeb["Client-side Services\n(ViaCep, Email, Reports)"]:::presentation
        SECWeb["Authentication & Security"]:::presentation
    end

    %% Service/Application Tier
    subgraph "Service/Application Tier"
        direction TB
        AppHost["AppHost\n(Static File Server & Proxy)"]:::service
        CoreLib["Core Library\n(Domain Models & DTOs)"]:::service
        ApiService["ApiService\n(Minimal API & Business Logic)"]:::service
        Endpoints["API Endpoints\n(Endpoints/*.cs)"]:::service
        Handlers["Business Logic Handlers"]:::service
        ServicesAPI["Email, Contract & Report Services"]:::service
        DbContext["AppDbContext & Mappings"]:::service
        Migrations["Database Migrations"]:::service
    end

    %% Data & External Integration Tier
    subgraph "Data & Integration Tier"
        direction TB
        Database["PostgreSQL\n(Docker)"]:::data
        ExternalViaCep["ViaCep HTTP API"]:::external
        ExternalSMTP["SMTP / Email Provider"]:::external
        ExternalStorage["File Storage\n(Local/Blob)"]:::external
    end

    %% Connections - Presentation to AppHost
    Browser -->|"loads UI"| AppHost
    AppHost -->|"serves Blazor files"| Browser
    WebApp -->|"uses components/pages"| CompPages
    CompPages -->|"invokes handlers"| HandlersWeb
    HandlersWeb -->|"calls client services"| ServicesWeb
    Browser -->|"auth flows"| SECWeb

    %% Presentation to Service calls
    ServicesWeb -->|HTTP JSON| AppHost
    WebApp -->|"shared models"| CoreLib

    %% AppHost to ApiService
    AppHost -->|"forwards API calls"| ApiService
    ApiService -->|"uses core models"| CoreLib

    %% Internal Service connections
    ApiService -->|"defines endpoints"| Endpoints
    Endpoints -->|"invoke handlers"| Handlers
    Handlers -->|"dependency injection"| ServicesAPI
    Handlers -->|"use DbContext"| DbContext
    DbContext -->|"queries"| Database
    Migrations -->|"migrate schema"| Database

    %% External integrations
    ServicesAPI -->|"send email"| ExternalSMTP
    ServicesAPI -->|"store/generated PDFs"| ExternalStorage
    ServicesWeb -->|"address lookup"| ExternalViaCep
    ApiService -->|"address lookup"| ExternalViaCep

    %% Shared Core usage
    CoreLib -->|"shared across"| ApiService
    CoreLib -->|"shared across"| WebApp

    %% Click Events
    click WebApp "https://github.com/israel-bsi/realtyhub/blob/main/Codigos/RealtyHub/RealtyHub.Web"
    click CompPages "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.Web/Components"
    click HandlersWeb "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.Web/Handlers"
    click ServicesWeb "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.Web/Services"
    click SECWeb "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.Web/Security"

    click AppHost "https://github.com/israel-bsi/realtyhub/blob/main/Codigos/RealtyHub/RealtyHub.AppHost"
    click ApiService "https://github.com/israel-bsi/realtyhub/blob/main/Codigos/RealtyHub/RealtyHub.ApiService"
    click CoreLib "https://github.com/israel-bsi/realtyhub/blob/main/Codigos/RealtyHub/RealtyHub.Core"
    click Endpoints "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.ApiService/Endpoints"
    click Handlers "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.ApiService/Handlers"
    click ServicesAPI "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.ApiService/Services"
    click DbContext "https://github.com/israel-bsi/realtyhub/blob/main/Codigos/RealtyHub/RealtyHub.ApiService/Data/AppDbContext.cs"
    click DbContext "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.ApiService/Data/Mappings"
    click Migrations "https://github.com/israel-bsi/realtyhub/tree/main/Codigos/RealtyHub/RealtyHub.ApiService/Migrations"

    %% Styles
    classDef presentation fill:#cfe2f3,stroke:#6fa8dc,stroke-width:1px,font-weight:bold
    classDef service fill:#d9ead3,stroke:#93c47d,stroke-width:1px,font-weight:bold
    classDef data fill:#e7e6e6,stroke:#999999,stroke-width:1px,font-weight:bold
    classDef external fill:#fce5cd,stroke:#f6b26b,stroke-width:1px,font-weight:bold
```
