# huidbk/huihome architecture

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

- Interactive diagram: https://gitdiagram.com/huidbk/huihome
- Repository: https://github.com/huidbk/huihome

## Overview

##### Main System Components
- Frontend: Represent the home_front component that serves the user interfaces (web pages for tenants, landlords, etc.). Emphasize that the front-end uses HTML, CSS, JavaScript (with Vue.js) and communicates with the backend API via JSON.
- Backend API Service: Represent the FastAPI-based service (mainly in the house_rental directory) that handles RESTful API requests. Subdivide this into key modules:
– Commons (including global exception handling, configuration, helper libraries)
– Routers (divided into admin, common, house, order, payment, and user submodules that expose the endpoints)
– Logic, Managers, and Models (for business logic, data model management, and ORM models)
– Middlewares (for authentication, JWT verification, logging, and request processing)
- Database: Represent the MySQL database (configured in conf/mysql.cnf and set up via the SQL scripts in resource/) as the central data store for users, houses, orders, etc.
- Cache: Represent Redis, which is used for caching (as seen with specific key naming conventions described in the README) to serve high-read scenarios like house information and SMS codes.
- External Services: Include components like:
– Qiniu OSS for handling images and file storage
– Third-party services for SMS (容联云), Payment (阿里支付), and Baidu Maps integration
- Deployment & Orchestration: Include Docker, docker-compose, and Nginx (configured in conf/nginx.conf) that orchestrates the API service and proxies requests.

##### Relationships and Data Flow
- User devices (client browsers or mobile applications) sending HTTP requests to the front-end.
- The front-end communicates (using JSON over HTTP) with the backend API endpoints.
- Within the backend, requests pass through middlewares (authentication, logging, rate-limiting) before reaching the appropriate routers.
- Routers delegate business logic to the Logic layer and interact with Managers, which in turn operate on Models (ORM).
- Database interactions occur via tortoise-orm linking to MySQL for persistent data.
- Redis is used alongside to cache frequently requested data (e.g., house details, SMS codes, area information) to improve performance.
- External services are accessed in various functionalities (e.g., sending SMS, processing payments) and are represented as integration points.
- Docker-compose manages the containers (MySQL container, Redis container, API container, and optionally Nginx) with dedicated configuration files.

##### Architectural Patterns & Design Principles
- Modular design: Clearly separated layers (routers, logic, managers, models, commons) reflecting a clean architecture.
- Asynchronous processing: Use of FastAPI’s async/await patterns, demonstrating non-blocking I/O for high-concurrency tasks.
- RESTful API Design: All endpoints follow REST principles and are documented (accessible at /docs upon starting the project).
- Dependency Injection: Use of FastAPI’s “Depends” mechanism in middleware (jwt_authentication, login_required) to inject security and context.
- Caching & Error Handling: Use of decorators for caching and error handling to manage performance and reliability.

##### Specific Elements
- Clear labels for each component:
- “Frontend (home_front)”
- “Backend API (FastAPI)” subdivided into: commons, routers (admin, common, house, order, payment, user), logic, managers, models, middlewares.
- “MySQL Database”
- “Redis Cache”
- “External Services (Qiniu OSS, SMS, Payment, Baidu Maps)”
- “Container Deployment (Docker/Docker Compose)”
- HTTP/JSON communications from the frontend to the backend
- API flow through middleware and routing layers
- Data persistence calls to MySQL
- Cache lookup calls to Redis
- Integration calls to external APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    U["User Device"]:::presentation
    FE["Frontend (home_front)"]:::presentation

    %% API Layer
    Backend["Backend API (FastAPI)"]:::backend
    BackendMain["main.py"]:::backend
    BackendServer["server.py"]:::backend
    Commons["Commons"]:::backend
    Middlewares["Middlewares"]:::backend
    Routers["Routers"]:::backend
    Logic["Logic"]:::logic
    Managers["Managers"]:::logic
    Models["Models"]:::logic

    %% Infrastructure Layer
    MySQL["MySQL Database"]:::infra
    SQLScripts["SQL Scripts"]:::infra
    Redis["Redis Cache"]:::infra
    External["External Services (Qiniu OSS, SMS,Payment,BaiduMaps)"]:::infra

    %% Deployment & Configuration
    Docker["Docker Deployment"]:::deployment
    DockerCompose["Docker Compose"]:::deployment
    Nginx["Nginx (Reverse Proxy)"]:::deployment

    %% Connections: Presentation to API
    U -->|"HTTP/JSON"| FE
    FE -->|"API Request"| Backend

    %% Backend internal flow
    Backend -->|"Runs"| BackendMain
    Backend -->|"Runs"| BackendServer
    Backend -->|"Utilizes"| Commons
    Backend -->|"Executes"| Middlewares
    Middlewares -->|"Routes"| Routers
    Routers -->|"Delegates"| Logic
    Logic -->|"Invokes"| Managers
    Logic -->|"Invokes"| Models
    Logic -->|"Integrates"| External
    Managers -->|"DB Ops"| MySQL
    Models -->|"ORM Query"| MySQL
    Managers -->|"Caches Data"| Redis
    Models -->|"Caches Data"| Redis

    %% Infrastructure and Deployment interactions
    MySQL -->|"Configured via"| DockerCompose
    Redis -->|"Configured via"| DockerCompose
    DockerCompose -->|"Orchestrates"| Docker
    DockerCompose -->|"Proxies Requests"| Nginx

    %% Class Definitions
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef logic fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef infra fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events
    click FE "https://github.com/huidbk/huihome/tree/master/home_front/"
    click Backend "https://github.com/huidbk/huihome/tree/master/house_rental/"
    click BackendMain "https://github.com/huidbk/huihome/blob/master/house_rental/main.py"
    click BackendServer "https://github.com/huidbk/huihome/blob/master/house_rental/server.py"
    click Commons "https://github.com/huidbk/huihome/tree/master/house_rental/commons/"
    click Routers "https://github.com/huidbk/huihome/tree/master/house_rental/routers/"
    click Logic "https://github.com/huidbk/huihome/tree/master/house_rental/logic/"
    click Managers "https://github.com/huidbk/huihome/tree/master/house_rental/managers/"
    click Models "https://github.com/huidbk/huihome/tree/master/house_rental/models/"
    click Middlewares "https://github.com/huidbk/huihome/tree/master/house_rental/middlewares/"
    click MySQL "https://github.com/huidbk/huihome/blob/master/conf/mysql.cnf"
    click SQLScripts "https://github.com/huidbk/huihome/tree/master/resource/"
    click Redis "https://github.com/huidbk/huihome/blob/master/conf/redis.conf"
    click External "https://github.com/huidbk/huihome/tree/master/house_rental/commons/libs/"
    click Docker "https://github.com/huidbk/huihome/tree/master/Dockerfile"
    click DockerCompose "https://github.com/huidbk/huihome/blob/master/docker-compose.yaml"
    click Nginx "https://github.com/huidbk/huihome/blob/master/conf/nginx.conf"
```
