# sv345922/arithmometer_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/sv345922/arithmometer_v2
- Repository: https://github.com/sv345922/arithmometer_v2

## Overview

##### Project Type & Purpose
- This is a full-stack service application focused on processing arithmetic expressions. The system handles the orchestration of tasks, where an orchestrator receives tasks, dispatches them to one or several calculators (workers), collects results, and updates a central SQLite database to maintain state.
- It exposes two interfaces: an HTTP API (for new expression submission and result retrieval) and a gRPC interface (for communication between orchestrator and calculators).

##### Analysis of the File Structure
- Notice several “cmd” directories such as:
- cmd/orch: Contains main.go for the orchestrator (server).
- cmd/calculator: Contains main.go for the calculator (worker) component.
- cmd/start: Implements automated spawning (automation of launching multiple calculators).
- cmd/test: Houses integration tests.
- The “client” directory holds a simple testing client.
- The “internal” directory comprises sub-packages that implement the core logic:
- internal/app and internal/calculator: Likely contain entrypoints for the application’s business logic.
- internal/grps: Implements gRPC components (both server and client parts).
- internal/dataBase: Provides connectivity and data handling for SQLite, including SQL query definitions.
- internal/useCases: Contains various use-cases such as login, registration, new expression handling, and task management.
- internal/parser: Parses expressions using a postfix notation approach.
- internal/taskQueue: Manages the task queue logic (handling deadlines, storage of queued tasks).
- Other utility and domain-specific modules (e.g., treeExpression, stack, timings, jwToken).
- Configuration and distribution files (distributive, go.mod, etc.) point to a well-structured modular codebase.

##### Key Components
a. External Interfaces:
- HTTP Server (listening on localhost:8000): Accepts new expressions and result queries.
- gRPC Server (listening on localhost:5000): Facilitates communication with calculators.
b. Orchestrator Service:
- Task Management: Fetches tasks from the SQLite database, dispatches tasks to calculators, and updates expression nodes.
- Persistence: Uses SQLite (as shown in db and internal/dataBase directories) for recovering state upon restart.
c. Calculator Service:
- Periodically requests tasks from the orchestrator.
- Computes arithmetic expressions (integrates with parser, treeExpression) and returns results.
d. Client:
- Provides an easy way for testers to submit expressions and view output.
e. Supporting Internal Components:
- Application Use Cases: authentication (planned), new expression processing, get result endpoint, etc.
- gRPC & HTTP endpoints inside internal packages.
- Parser and expression evaluation modules that implement arithmetic computation.
- Task Queue handling modules that control deadlines and error-checking (e.g., division by zero).

##### Relationships & Data Flow
- The client submits a POST request (new expression) to the HTTP endpoint.
- The orchestrator receives the expression, stores it in the SQLite DB, and queues a new task.
- The calculator(s) periodically poll the orchestrator via gRPC for pending tasks.
- Once a calculator accepts a task, it computes the result and sends it back to the orchestrator.
- The orchestrator then updates the state in the database (or in-memory model) and, if needed, informs the client (or the client may poll for results via a GET request).
- For error conditions (such as division by zero), the orchestrator updates the task state accordingly.

##### Architectural Patterns & Design Principles
- Layered/Microservice-like Architecture: Clear separation between client, orchestrator (API layer and business logic), and calculators (worker nodes).
- Resilience via Persistence: Using SQLite to persist state for fault-tolerance.
- Asynchronous Task Processing: Via task queue and worker model.
- A combination of HTTP and gRPC for different communication needs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Interface"
        CLIENT["Client Interface"]:::client
    end

    %% Orchestrator Service
    subgraph "Orchestrator Service"
        HTTP_API["HTTP API Endpoint"]:::api
        GRPC_Server["gRPC Server (Orchestrator)"]:::orchestrator
        Task_Manager["Task Manager"]:::orchestrator
        TASK_QUEUE["Task Queue"]:::task
        PERSISTENCE["SQLite DB"]:::database
    end

    %% Calculator Service
    subgraph "Calculator Service"
        GRPC_Client["gRPC Client (Calculator)"]:::orchestrator
        CALCULATOR["Calculator Worker"]:::calculator
        EXP_PARSER["Expression Parser"]:::calculator
    end

    %% Data Flow Connections
    CLIENT -->|"POST_expression"| HTTP_API
    CLIENT -->|"GET_result"| HTTP_API

    HTTP_API -->|"createTask"| Task_Manager
    Task_Manager -->|"enqueueTask"| TASK_QUEUE
    Task_Manager -->|"updateResult"| PERSISTENCE

    GRPC_Server -->|"dispatchTask"| GRPC_Client
    GRPC_Client -->|"deliverTask"| CALCULATOR
    CALCULATOR -->|"computeExpression"| EXP_PARSER
    CALCULATOR -->|"submitResult"| GRPC_Client
    GRPC_Client -->|"returnResult"| GRPC_Server

    %% Click Events
    click HTTP_API "https://github.com/sv345922/arithmometer_v2/blob/main/cmd/orch/main.go"
    click HTTP_API "https://github.com/sv345922/arithmometer_v2/blob/main/internal/app/server.go"

    click GRPC_Server "https://github.com/sv345922/arithmometer_v2/blob/main/internal/grps/grpcServer/grpcServer.go"
    click GRPC_Client "https://github.com/sv345922/arithmometer_v2/blob/main/internal/grps/client/grpcClient.go"

    click Task_Manager "https://github.com/sv345922/arithmometer_v2/blob/main/internal/useCases/newExpression/endpoint.go"
    click Task_Manager "https://github.com/sv345922/arithmometer_v2/tree/main/internal/useCases/getTask"

    click TASK_QUEUE "https://github.com/sv345922/arithmometer_v2/blob/main/internal/taskQueue/queue.go"

    click PERSISTENCE "https://github.com/sv345922/arithmometer_v2/blob/main/internal/dataBase/dataBase.go"
    click PERSISTENCE "https://github.com/sv345922/arithmometer_v2/blob/main/db/database.db"

    click CALCULATOR "https://github.com/sv345922/arithmometer_v2/blob/main/cmd/calculator/main.go"
    click CALCULATOR "https://github.com/sv345922/arithmometer_v2/blob/main/internal/calculator/service.go"

    click EXP_PARSER "https://github.com/sv345922/arithmometer_v2/blob/main/internal/parser/parser.go"
    click EXP_PARSER "https://github.com/sv345922/arithmometer_v2/blob/main/internal/parser/node.go"

    click CLIENT "https://github.com/sv345922/arithmometer_v2/blob/main/client/appClient/service.go"
    click CLIENT "https://github.com/sv345922/arithmometer_v2/blob/main/client/client.go"

    %% Styles
    classDef client fill:#b3ffb3,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef calculator fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef database fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef api fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef task fill:#f0e68c,stroke:#333,stroke-width:2px;
```
