How bang-tv259/netease works
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.