# devbrains-com/swisstaxcalculator architecture

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

- Interactive diagram: https://gitdiagram.com/devbrains-com/swisstaxcalculator
- Repository: https://github.com/devbrains-com/swisstaxcalculator

## Overview

##### Main Components
- Frontend/UI Layer: Represented by Nuxt 3 with Vue components (e.g., app.vue, pages/index.vue, and other components in the components folder). Note the use of assets (CSS files) and form-related components (e.g., those inside components/formkit and components/global).
- Server/API Layer: The server folder (server/api) hosts API routes such as inputdata.get.ts, locations.get.ts, and taxes.post.ts. These endpoints receive client requests and forward them to the business logic for processing.
- Business Logic / Tax Calculation Layer: The core tax logic lives in the lib/taxes directory. This layer includes modules for different tax aspects – deductions, factors, income, pension capital, personnel, tariffs, and more. Each sub-folder deals with specific tax rules and calculations.
- Data Layer: This project uses file-based data storage. The data folder is split into raw (initial JSON files from external sources) and parsed directories (organized per year, canton and tax category). Data is imported at build time (via the yarn importdata script) and held in memory during execution.
- Utility and Support Modules: Other directories such as inputs, lib/utils, modules, and utils support both the UI components and tax logic with common functions and configurations (e.g., formkit.config.ts, tsconfig.json).

- Data Flow from the Client to the Server:
- Client (Nuxt pages and Vue components) sends user input (e.g., tax-related values) through the UI.
- These inputs trigger API requests (server/api/taxes.post.ts for tax calculations, server/api/locations.get.ts for retrieving location data, etc.).
- Server API and Business Logic Interaction:
- API endpoints receive the requests, validate input data, and forward them to the tax calculation modules found in lib/taxes.
- The tax logic uses various data helpers, constants, and data importers to calculate results based on the loaded raw/parsed data.
- Data Handling:
- Data is initially brought in by the import process (using yarn importdata) from the data/raw folder and organized into the data/parsed folder. Once imported, the file-based data is loaded into memory.
- Integration of Utility Modules:
- Shared utilities (in lib/utils, utils, and inputs) assist both the frontend and business logic layers with additional data operations (e.g., formatting, currency calculations with DineroJS, array formatting).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Components and pages handle presentation; server/api routes manage the HTTP layer; business logic is strictly isolated in the lib/taxes module; and raw data is handled separately.
- Modular Design: The tax calculations are broken into submodules (deduction, factor, income, etc.), promoting reusability and easier maintenance.
- Static Deployment & In-Memory Data Optimization: The design emphasizes static deployment where tax data is pre-parsed and efficiently loaded into memory for quick calculations.

##### Essential Elements
- UI Components and API endpoints.
- API endpoints and the tax business logic.
- Business logic and the file-based data layer.
- Notes for any significant design practices such as the in-memory loading for speed and the modular separation within lib/taxes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Nuxt 3 Frontend"]:::frontend
        FE_A["app.vue"]:::frontend
        FE_B["pages/index.vue"]:::frontend
        subgraph "Components"
            FE_C["FormKit: autocomplete.vue"]:::frontend
            FE_C2["FormKit: buttonSelect.vue"]:::frontend
            FE_D["Global: button.vue"]:::frontend
        end
        subgraph "Assets"
            FE_E["CSS: form.css"]:::frontend
            FE_F["CSS: main.css"]:::frontend
        end
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        API1["API Endpoints"]:::backend
        API_A["inputdata.get.ts"]:::backend
        API_B["locations.get.ts"]:::backend
        API_C["taxes.post.ts"]:::backend
    end

    %% Tax Calculation Engine
    subgraph "Tax Calculation Engine"
        TAX1["lib/taxes Core"]:::backend
        subgraph "Submodules"
            TAX_Deduction["deduction"]:::backend
            TAX_Factor["factor"]:::backend
            TAX_Income["income"]:::backend
            TAX_Pension["pensionCapital"]:::backend
            TAX_Personnel["personnel"]:::backend
            TAX_Tarif["tarif"]:::backend
        end
        TAX_Constants["constants.ts"]:::backend
        TAX_Helpers["helpers.ts"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        DATA_Raw["Raw Data Store"]:::data
        DATA_Parsed["Parsed Data Store"]:::data
    end

    %% Utility & Support Modules
    subgraph "Utility & Support Modules"
        UTIL_Inputs["Input Helpers"]:::utility
        subgraph "Generic Utilities"
            GEN_LIB["lib/utils"]:::utility
            GEN_UTILS["utils"]:::utility
        end
        subgraph "Configuration & Build Tools"
            CONF_Formkit["formkit.config.ts"]:::utility
            CONF_Nuxt["nuxt.config.ts"]:::utility
            CONF_Tailwind["tailwind.config.js"]:::utility
            CONF_TS["tsconfig.json"]:::utility
        end
        UTIL_Modules["Modules"]:::utility
    end

    %% Build & Import Tools
    subgraph "Build & Import Tools"
        BUILD_Import["yarn importdata"]:::build
    end

    %% Connections
    FE1 -->|"sends_user_input"| API1
    API1 -->|"delegates_processing"| TAX1
    TAX1 -->|"loads_parsed_data"| DATA_Parsed
    BUILD_Import -->|"imports_raw_data"| DATA_Raw
    DATA_Raw -->|"parses_into"| DATA_Parsed

    %% API Endpoints inside Server/API Layer
    API1 --> API_A
    API1 --> API_B
    API1 --> API_C

    %% Tax Calculation Submodules connection (implicitly part of TAX1)
    TAX1 --> TAX_Deduction
    TAX1 --> TAX_Factor
    TAX1 --> TAX_Income
    TAX1 --> TAX_Pension
    TAX1 --> TAX_Personnel
    TAX1 --> TAX_Tarif
    TAX1 --> TAX_Constants
    TAX1 --> TAX_Helpers

    %% Click Events for Frontend Layer
    click FE_A "https://github.com/devbrains-com/swisstaxcalculator/blob/master/app.vue"
    click FE_B "https://github.com/devbrains-com/swisstaxcalculator/blob/master/pages/index.vue"
    click FE_C "https://github.com/devbrains-com/swisstaxcalculator/blob/master/components/formkit/autocomplete.vue"
    click FE_C2 "https://github.com/devbrains-com/swisstaxcalculator/blob/master/components/formkit/buttonSelect.vue"
    click FE_D "https://github.com/devbrains-com/swisstaxcalculator/blob/master/components/global/button.vue"
    click FE_E "https://github.com/devbrains-com/swisstaxcalculator/blob/master/assets/css/form.css"
    click FE_F "https://github.com/devbrains-com/swisstaxcalculator/blob/master/assets/css/main.css"

    %% Click Events for Server/API Layer
    click API_A "https://github.com/devbrains-com/swisstaxcalculator/blob/master/server/api/inputdata.get.ts"
    click API_B "https://github.com/devbrains-com/swisstaxcalculator/blob/master/server/api/locations.get.ts"
    click API_C "https://github.com/devbrains-com/swisstaxcalculator/blob/master/server/api/taxes.post.ts"

    %% Click Events for Tax Calculation Engine
    click TAX1 "https://github.com/devbrains-com/swisstaxcalculator/tree/master/lib/taxes/"
    click TAX_Constants "https://github.com/devbrains-com/swisstaxcalculator/blob/master/lib/taxes/constants.ts"
    click TAX_Helpers "https://github.com/devbrains-com/swisstaxcalculator/blob/master/lib/taxes/helpers.ts"

    %% Click Events for Data Layer
    click DATA_Raw "https://github.com/devbrains-com/swisstaxcalculator/tree/master/data/raw/"
    click DATA_Parsed "https://github.com/devbrains-com/swisstaxcalculator/tree/master/data/parsed/"

    %% Click Events for Utility & Support Modules
    click UTIL_Inputs "https://github.com/devbrains-com/swisstaxcalculator/tree/master/inputs/"
    click GEN_LIB "https://github.com/devbrains-com/swisstaxcalculator/blob/master/lib/utils/array.ts"
    click GEN_UTILS "https://github.com/devbrains-com/swisstaxcalculator/blob/master/utils/formatUtils.ts"
    click CONF_Formkit "https://github.com/devbrains-com/swisstaxcalculator/blob/master/formkit.config.ts"
    click CONF_Nuxt "https://github.com/devbrains-com/swisstaxcalculator/blob/master/nuxt.config.ts"
    click CONF_Tailwind "https://github.com/devbrains-com/swisstaxcalculator/blob/master/tailwind.config.js"
    click CONF_TS "https://github.com/devbrains-com/swisstaxcalculator/blob/master/tsconfig.json"
    click UTIL_Modules "https://github.com/devbrains-com/swisstaxcalculator/blob/master/modules/copyDataModule.ts"

    %% Class Definitions for colors
    classDef frontend fill:#FFDDC1,stroke:#D2691E,stroke-width:2px;
    classDef backend fill:#C1E1FF,stroke:#4682B4,stroke-width:2px;
    classDef data fill:#C1FFC1,stroke:#228B22,stroke-width:2px;
    classDef utility fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef build fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
```
