# bang-tv259/netease architecture

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

- Interactive diagram: https://gitdiagram.com/bang-tv259/netease
- Repository: https://github.com/bang-tv259/netease

## Overview

##### Project Type and Purpose
- NetEase is a full-stack application designed for salary processing. It converts Gross salary to Net salary and supports batch processing through Excel file uploads.
- The project follows a monorepo architecture with two main areas: the backend (located in the "src/cat" directory) and the frontend (located in the "packages/dev_ui" directory).

##### Main Components
a. Frontend:
- Located in packages/dev_ui.
- Uses a Streamlit interface (see the run command for Homepage.py) to provide a user-friendly UI for salary conversion and file uploading.
b. Backend:
- Located in src/cat.
- API layer is built with FastAPI (see src/cat/api/main.py).
- Contains API routers (under src/cat/api/routers) that manage endpoints for tasks (such as net_ease operations).
- Core business logic under src/cat/core/net_ease handles the calculation, constants, DTOs, and business services.
c. Common/Configuration:
- Both "packages/dev_ui" and "src/cat" have common directories for configurations (ex. packages/dev_ui/src/dev_ui/common/config and src/cat/common/config) which standardizes environment settings and base configurations.
d. External Dependencies/Tools:
- Tools like uv, just, and watchexec support dependency management, formatting, linting, and automated test-run setups.
- Excel file processing is a critical function for batch processing of salary data.

##### Relationships and Interactions
- The frontend (Streamlit UI) communicates with the backend API (FastAPI) to obtain computed Net salary results.
- User interactions on the UI trigger API calls to endpoints defined in src/cat/api/routers (the net_ease endpoint specifically).
- The backend processes the request using its core net_ease logic by calling controllers, services, and applying DTOs to handle data.
- There is also an Excel upload process where the UI supports file submission, and the backend processes the file to extract salary data and returns calculated results.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between UI (presentation layer) and the API/backend (business logic layer).
- Modular Structure: The monorepo is split into distinct packages (dev_ui for frontend and cat for backend) with their own configurations and utilities.
- Dependency Injection and Config Abstraction: Configuration files and shared utilities in the common folders suggest an approach that encourages reusability and separation of environment-specific settings.
- API-Driven Communication: The system leverages HTTP endpoints (via FastAPI) for client-server communication.

##### Relevant Technologies and Frameworks
- Frontend: Streamlit for rendering the web interface.
- Backend: FastAPI for serving HTTP endpoints.
- Python-based tooling: uv (for dependency management), just (for task running) and watchexec (for automated testing).
- Excel file handling: Though not explicitly stated, functionality for handling Excel files in the backend likely leverages a Python library for Excel I/O.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_UI["Streamlit UI"]:::frontend
        FE_Sal["Salary Conversion Page"]:::frontend
        FE_Upload["File Upload Page"]:::frontend
        FE_Config["Frontend Config"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE_API["FastAPI API"]:::backend
        BE_Router["API Routers: net_ease"]:::backend
        BE_Core["Core Salary Calculation Logic"]:::backend
        BE_Config["Backend Config"]:::backend
    end

    %% Dev Tools
    subgraph "Dev Tools"
        DEV["External Tools"]:::devtool
    end

    %% Data Flow and Relationships
    FE_UI -->|"triggers"| BE_API
    FE_UI -->|"navigatesTo"| FE_Sal
    FE_UI -->|"navigatesTo"| FE_Upload
    FE_UI -->|"uses"| FE_Config

    BE_API -->|"routesTo"| BE_Router
    BE_Router -->|"processesWith"| BE_Core
    BE_Core -->|"configuresWith"| BE_Config

    DEV -->|"supports"| BE_API
    DEV -->|"supports"| FE_UI

    %% Styles for colors
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C6FFC6,stroke:#333,stroke-width:2px;
    classDef devtool fill:#F7E2AD,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE_UI "https://github.com/bang-tv259/netease/blob/main/packages/dev_ui/src/dev_ui/ui/Homepage.py"
    click FE_Sal "https://github.com/bang-tv259/netease/blob/main/packages/dev_ui/src/dev_ui/ui/pages/💬_Gross_Net.py"
    click FE_Upload "https://github.com/bang-tv259/netease/blob/main/packages/dev_ui/src/dev_ui/ui/pages/📁_Upload_files.py"
    click FE_Config "https://github.com/bang-tv259/netease/blob/main/packages/dev_ui/src/dev_ui/common/config/base.py"
    click BE_API "https://github.com/bang-tv259/netease/blob/main/src/cat/api/main.py"
    click BE_Router "https://github.com/bang-tv259/netease/blob/main/src/cat/api/routers/net_ease.py"
    click BE_Core "https://github.com/bang-tv259/netease/tree/main/src/cat/core/net_ease"
    click BE_Config "https://github.com/bang-tv259/netease/blob/main/src/cat/common/config/base.py"
    click DEV "https://github.com/bang-tv259/netease/blob/main/uv.lock"
```
