# florentinlavaud/jinka architecture

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

- Interactive diagram: https://gitdiagram.com/florentinlavaud/jinka
- Repository: https://github.com/florentinlavaud/jinka

## Overview

##### Project type and purpose
- This is a lightweight, single-machine Python application with both a simple GUI and a CLI interface.
- It acts as a wrapper around the external Jinka API: authenticating, fetching apartment alerts, cleaning expired offers, and exporting the results to CSV/Excel.

##### Break down the file structure and map to components
- src/main.py
- Entry point. Parses CLI arguments or launches the GUI.
- Orchestrates the workflow: authentication → data fetch → cleaning → export.
- src/api_utils.py
- Encapsulates all HTTP interactions with the Jinka API: login, fetch alerts, delete expired offers.
- src/processing_utils.py
- Takes raw JSON or HTML data, cleans and normalizes it, builds pandas DataFrame, and exports CSV/Excel.
- requirements.txt
- Lists external libraries (e.g., requests, pandas, openpyxl, a GUI toolkit such as Tkinter or PySimpleGUI).
- Local JSON credential store (created at runtime if “save credentials” is used).

##### Main components
A. User Interface Layer
- GUI (if no CLI args)
- CLI Parser (argparse in main.py)
B. Core Orchestrator (main.py)
- Authenticator
- Workflow Controller
C. API Client (api_utils.py)
- Jinka API:
- POST /login
- GET /alerts
- POST /delete_offer
D. Data Processing Module (processing_utils.py)
- Data Cleaner & Normalizer
- Exporter (CSV & Excel)
E. Local Storage
- Credentials JSON (optional, unencrypted)
- Output folder/files (dataset.csv, dataset.xlsx)
F. External System
- Jinka API over HTTPS

##### Relationships and data flows
1. User invokes main.py via GUI or CLI.
2. Main.py reads/stores credentials (Credentials JSON ↔ Main).
3. Main → API Client: authenticate.
4. Main → API Client: fetch alerts → raw data.
5. Main → Data Processor: clean/filter expired, build DataFrame.
6. If cleaning enabled: Main → API Client: delete expired offers.
7. Data Processor → write CSV/Excel files to disk.
8. Main returns success/error to UI.

##### Architectural patterns and principles
- Separation of concerns: UI, orchestration, API client, data processing are in distinct modules.
- Single responsibility: each utility module has a focused role.
- Local-only footprint: no microservices or databases, just file I/O and network calls.

##### Technologies and frameworks to annotate
- Python 3.x runtime
- requests (HTTP client)
- pandas (data manipulation)
- openpyxl or xlsxwriter (Excel export)
- argparse (CLI) and/or PySimpleGUI/Tkinter (GUI)

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "User Interface Layer"
    GUI["GUI (PySimpleGUI/Tkinter)"]:::ui
    CLI["CLI Parser (argparse)"]:::ui
  end

  subgraph "Core Logic"
    CoreOrch["Core Orchestrator"]:::core
    Auth["Authenticator"]:::core
    Work["Workflow Controller"]:::core
  end

  subgraph "Modules"
    subgraph "API Client Module"
      APIClient["Jinka API Client"]:::core
    end
    subgraph "Data Processing Module"
      DataProcessor["Data Cleaner & Normalizer & Exporter"]:::core
    end
  end

  subgraph "External & Storage"
    JSONCreds["Credentials JSON"]:::storage
    Outputs["Output Files (CSV/Excel)"]:::storage
    Requirements["requirements.txt"]:::storage
    JinkaAPI["Jinka API (HTTPS)"]:::external
  end

  GUI -->|"invoke"| CoreOrch
  CLI -->|"invoke"| CoreOrch
  CoreOrch -->|"load/save credentials"| JSONCreds
  CoreOrch -->|"authenticate"| Auth
  Auth -->|"call API"| APIClient
  CoreOrch -->|"fetch alerts"| APIClient
  APIClient -->|"alerts JSON"| CoreOrch
  CoreOrch -->|"process data"| DataProcessor
  CoreOrch -->|"delete expired offers"| APIClient
  DataProcessor -->|"export CSV/Excel"| Outputs
  CoreOrch -->|"report success/error"| GUI
  CoreOrch -->|"report success/error"| CLI
  APIClient -->|"HTTPS requests"| JinkaAPI

  click GUI "https://github.com/florentinlavaud/jinka/blob/master/src/main.py"
  click CLI "https://github.com/florentinlavaud/jinka/blob/master/src/main.py"
  click Work "https://github.com/florentinlavaud/jinka/blob/master/src/main.py"
  click APIClient "https://github.com/florentinlavaud/jinka/blob/master/src/api_utils.py"
  click DataProcessor "https://github.com/florentinlavaud/jinka/blob/master/src/processing_utils.py"
  click Requirements "https://github.com/florentinlavaud/jinka/blob/master/requirements.txt"

  classDef ui fill:#AEDFF7,stroke:#0366d6,color:#000;
  classDef core fill:#ACF7AC,stroke:#228B22,color:#000;
  classDef storage fill:#E0E0E0,stroke:#696969,color:#000;
  classDef external fill:#F2F2F2,stroke:#808080,color:#000;
```
