# nguyenhoangviethung/apartment-management architecture

> Architecture diagram of the GitHub repository nguyenhoangviethung/apartment-management, 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/nguyenhoangviethung/apartment-management
- Repository: https://github.com/nguyenhoangviethung/apartment-management

## Overview

##### Project Overview and Type
- This is a full‐stack apartment management application with a mobile UI built in Flutter and a backend built using Flask.
- The app is designed to manage apartment aspects such as authentication, fee management, residents, rooms, payments, and news/notifications.

##### Main Components

A. Frontend (Mobile and Web – Flutter)
- Flutter Mobile Application: Displays multiple screens such as authentication (login, register, password reset), home/dashboard, management panels for fees, residents, rooms, vehicles, notifications, and payment interfaces (integration with vnpay).
- Support for Web (optional) and platform-specific directories for Android and iOS.
- UI Layer: Organized under "frontend/lib/view" that separates authentication, home, and management related screens.
- Utilizes models (e.g., account_info, contribution_fee_info, etc.) and services (fetching data from backend endpoints).

B. Backend (Flask API)
- API Layer: Found under "backend/api" with submodules for admin, auth, news, pay, and user.
- Admin Endpoints: Administrative tasks (e.g., dashboard management).
- Auth Endpoints: Authentication processes.
- News Module: Handles news, crawling, data extraction, and testing.
- Payment Endpoints: Implements payment logic likely coordinating with vnpay.
- User Endpoints: Manages user-related functionalities.
- Middleware and Extensions: Custom middlewares (e.g., authentication, logging), and extensions that enhance or configure Flask’s capabilities.
- Services Layer: Contains business logic split into various service files (e.g., fee_service, resident_service, transaction_service). They encapsulate integration with external services like Cloudinary (via cloudinary_service) and possibly handle fee contributions, household data, etc.
- Models and Database: The "backend/models" directory includes SQL initialization scripts (init.sql) and a schema defined in models.py.
- External Integrations: Payment integration (“vnpay” directory) and cloud-related media service using Cloudinary.

C. Supporting Components:
- Configuration files (backend/config.py, environment.yml, requirements.txt) for setting up the environment.
- Deployment and CI artifacts, such as GitHub workflows in backend/github/workflows.
- Static assets for API documentation or front-facing content (swagger.yaml, styles.css, transaction_success.html).

##### Relationships and Interactions
- Frontend sends HTTP(S) requests (RESTful API calls) to the Flask backend.
- The Backend API layer handles client requests and routes them to the appropriate controllers (e.g., auth, user, news, payment).
- Business logic in the Services layer processes the requests and communicates with the Database (models) for persistent data storage.
- External Services: The backend interacts with third-party services (e.g., payment system via vnpay, Cloudinary for media management).
- Middleware applies common logic across requests before hitting the endpoint logic (e.g., user authentication, logging, error handling).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear separation between API routing, business logic (services), and data access (models).
- Modularization: Both backend and frontend are organized into modules (e.g., multiple API submodules and distinct Flutter views/services).
- Client-Server Interaction: The Flutter frontend communicates asynchronously with the Flask backend via RESTful endpoints.
- Integration with External Services: Payment processing (vnpay) and cloud storage (Cloudinary) are encapsulated in service classes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FM["Flutter Mobile App"]:::frontend
        FA["Auth Screens"]:::frontend
        FH["Home Screens"]:::frontend
        FMd["Flutter Models"]:::frontend
        FServ["Flutter Services"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        subgraph "API Endpoints"
            BInit["Backend Init"]:::backend
            BAuth["Auth Endpoints"]:::backend
            BAdmin["Admin Endpoints"]:::backend
            BNews["News Module"]:::backend
            BPay["Payment Endpoints"]:::backend
            BUser["User Endpoints"]:::backend
            BMiddleware["Middleware"]:::backend
            BExtensions["Flask Extensions"]:::backend
        end

        subgraph "Services & Data"
            BService["Business Logic Services"]:::service
            BDB["Database"]:::db
            Bvnpay["vnpay Integration"]:::external
            Cloudinary["Cloudinary Integration"]:::external
        end

        subgraph "Static & Config"
            BStatic["API Static Assets"]:::backend
            BTemplates["Templates"]:::backend
            BConfig["Backend Config"]:::backend
            BEnv["Env & Requirements"]:::backend
            BDeploy["Deployment Workflows"]:::backend
        end
    end

    %% Frontend Internal Connections
    FM -->|"contains"| FA
    FM -->|"contains"| FH
    FM -->|"contains"| FMd
    FM -->|"contains"| FServ

    %% Interaction between Frontend and Backend
    FM -->|"REST_call"| BInit

    %% Backend API Endpoints to Business Logic Services
    BInit -->|"routes_to"| BAuth
    BInit -->|"routes_to"| BAdmin
    BInit -->|"routes_to"| BNews
    BInit -->|"routes_to"| BPay
    BInit -->|"routes_to"| BUser
    BInit -->|"applies"| BMiddleware
    BInit -->|"loads"| BExtensions

    BAuth -->|"processes"| BService
    BAdmin -->|"processes"| BService
    BNews -->|"processes"| BService
    BPay -->|"processes"| BService
    BUser -->|"processes"| BService
    BMiddleware -->|"checks"| BService
    BExtensions -->|"enables"| BService

    %% Business Logic Services interactions
    BService -->|"stores"| BDB
    BService -->|"calls"| Bvnpay
    BService -->|"uploads_to"| Cloudinary

    %% Backend Configurations and Assets
    BInit -->|"serves"| BStatic
    BInit -->|"serves"| BTemplates
    BInit -->|"configures"| BConfig
    BConfig -->|"includes"| BEnv
    BConfig -->|"triggers"| BDeploy

    %% Click Events for Frontend
    click FM "https://github.com/nguyenhoangviethung/apartment-management/tree/main/frontend/lib/view"
    click FA "https://github.com/nguyenhoangviethung/apartment-management/tree/main/frontend/lib/view/authentication"
    click FH "https://github.com/nguyenhoangviethung/apartment-management/tree/main/frontend/lib/view/home"
    click FMd "https://github.com/nguyenhoangviethung/apartment-management/tree/main/frontend/lib/models"
    click FServ "https://github.com/nguyenhoangviethung/apartment-management/tree/main/frontend/lib/services"

    %% Click Events for Backend
    click BInit "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/app.py"
    click BAuth "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/auth/routes.py"
    click BAdmin "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/admin/routes.py"
    click BNews "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/api/news"
    click BPay "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/pay/routes.py"
    click BUser "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/user/routes.py"
    click BMiddleware "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/middlewares.py"
    click BExtensions "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/api/extensions.py"
    click BService "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/services"
    click BDB "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/models"
    click Bvnpay "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/vnpay"
    click BStatic "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/api/static"
    click BTemplates "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/api/templates"
    click BConfig "https://github.com/nguyenhoangviethung/apartment-management/blob/main/backend/config.py"
    click BEnv "https://github.com/nguyenhoangviethung/apartment-management/blob/main/environment.yml"
    click BDeploy "https://github.com/nguyenhoangviethung/apartment-management/tree/main/backend/github/workflows"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef backend fill:#fcc,stroke:#333,stroke-width:2px;
    classDef service fill:#fea,stroke:#333,stroke-width:2px;
    classDef db fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#eef,stroke:#333,stroke-width:2px;
```
