How florentinlavaud/jinka works
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)