# javieracost/flarelyzer architecture

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

- Interactive diagram: https://gitdiagram.com/javieracost/flarelyzer
- Repository: https://github.com/javieracost/flarelyzer

## Overview

##### Project type and purpose
- Flarelyzer is a desktop, open-source, real-time monitoring tool for the MMORPG Tibia.
- It passively reads the Tibia client’s process memory and server log messages to detect rare‐drop events, then issues desktop notifications.

##### File structure
- Top‐level scripts:
- Flarelyzer.py – main orchestrator
- memscan.py – low‐level memory‐scanning routines
- agent.py – “interesting items” configuration and detection logic
- constants.py – memory offsets, config constants
- Data directory:
- Database/
– database.db (SQLite store for stats/logs)
– pluralMap.csv (mapping item names/plurals)
- Other:
- LICENSE, README.md, .gitignore

##### Key insights from the README
- Written in Python (runs on PyPy for performance).
- Uses libnotify-bin to send desktop notifications.
- Currently CLI‐driven, future UI planned (Qt).
- Configurable “interesting” items in agent.py.

##### Main components & interactions
a. External System
– Tibia Client Process
b. Core Flarelyzer Process (PyPy interpreter) with subcomponents:
1. Memory Scanner (memscan.py / constants.py)
- Attaches to Tibia process, reads memory to extract server log buffers & chat text
2. Log Parser & Event Detector (part of Flarelyzer.py + agent.py)
- Parses raw text lines, applies “interesting” item rules from agent.py
3. Data Store (Database/database.db + pluralMap.csv)
- Records events, helps normalize item names via pluralMap.csv
4. Notifier (libnotify-bin calls)
- Sends desktop popups on rare‐drop detection
c. External dependencies
– PyPy runtime
– libnotify-bin (OS notification service)

##### Relationships & data flows
1. Flarelyzer → attaches → Tibia Client Memory
2. Memory Scanner → extracts → raw log text
3. Parser/Agent → processes → raw text → detection events
4. Parser/Agent ↔ reads/writes ↔ Database files
5. Notifier ← receives events ← Parser/Agent
6. User sees desktop notification

##### Architectural patterns & design principles
- Modular separation: scanning, parsing/detection, storage, notification
- Single process with clear internal layers
- File‐based configuration & data persistence
- Passive instrumentation (no client modification)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    Tibia["Tibia Client Process"]:::external

    %% Flarelyzer Process Container
    subgraph "Flarelyzer Process (PyPy)" 
        direction TB
        MemScan["Memory Scanner"]:::scanner
        Constants["Config Constants"]:::scanner
        Parser["Log Parser & Event Detector"]:::parser
        AgentConfig["Interesting Items Config"]:::parser
        subgraph "Data Store" 
            direction TB
            SQLiteDB["SQLite Database"]:::datastore
            PluralMap["Plural Map CSV"]:::datastore
        end
        Notifier["Notifier (libnotify-bin)"]:::notifier
    end

    %% External Notification Service
    OSNotify["OS Notification Service"]:::external

    %% Data Flows
    Tibia -->|"raw memory/log data"| MemScan
    MemScan -->|"raw log text"| Parser
    Parser -->|"reads config"| AgentConfig
    Parser -->|"DB read/write"| SQLiteDB
    SQLiteDB -->|"DB read"| Parser
    Parser -->|"CSV lookup"| PluralMap
    Parser -->|"detection events"| Notifier
    Notifier -->|"desktop popup"| OSNotify

    %% Click Events
    click MemScan "https://github.com/javieracost/flarelyzer/blob/master/memscan.py"
    click Constants "https://github.com/javieracost/flarelyzer/blob/master/constants.py"
    click FlarelyzerMain "https://github.com/javieracost/flarelyzer/blob/master/Flarelyzer.py"
    click AgentConfig "https://github.com/javieracost/flarelyzer/blob/master/agent.py"
    click SQLiteDB "https://github.com/javieracost/flarelyzer/blob/master/Database/database.db"
    click PluralMap "https://github.com/javieracost/flarelyzer/blob/master/Database/pluralMap.csv"

    %% Styles
    classDef external fill:#eeeeee,stroke:#555,stroke-width:1px;
    classDef scanner fill:#cfe2ff,stroke:#1f77b4,stroke-width:2px;
    classDef parser fill:#d4edda,stroke:#2ca02c,stroke-width:2px;
    classDef datastore fill:#f8d7da,stroke:#d62728,stroke-width:2px,stroke-dasharray: 5 5;
    classDef notifier fill:#fff4ce,stroke:#ff7f0e,stroke-width:2px;
```
