# andrick-dms/dms-automatedidreader architecture

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

- Interactive diagram: https://gitdiagram.com/andrick-dms/dms-automatedidreader
- Repository: https://github.com/andrick-dms/dms-automatedidreader

## Overview

##### Project type and purpose
- This is a Windows-based, Python-written, background “tray” service plus an administrative dashboard.
- Purpose: automatically read Costa Rican ID cards (or QR codes), decode personal data, and auto-fill guest forms in the Lenel system.  It also includes a licensing mechanism, per-customer installer generation, and runtime configuration management.

##### File structure (focus on the v3.2 folder)
- dashboard.py – the entry point for the installer-generator dashboard UI.
- requirements.txt – Python dependencies (e.g., pyautogui, serial, XOR library).
- template/
– main.py – logic to generate new configuration templates.
– crear_configuracion.py – routines to build user-customized form-filling rules.

##### README for clues
- Tray-service that detects COM port, reads QR or physical ID via hardware reader.
- Decodes with XOR algorithm, extracts fields (ID number, name, birthdate, expiration).
- Uses pyautogui to simulate keyboard input into Lenel forms.
- Supports multiple “configs” to define field order/tab counts.
- Licensing: local cache, first-launch prompt, log activation events.

1. Hardware Interface
- ID/QR reader on COM port
- COM-port detection module
2. Decoder Module
- XOR decoder logic
- Data extraction
3. Tray-Service Application
- Configuration manager (loads active config from disk)
- Autocomplete engine (pyautogui scripts)
- License manager (checks/validates license cache)
- Logging subsystem (writes events to local log files)
4. Configuration Template Generator
- Runs from tray UI or standalone script (template/main.py, crear_configuracion.py)
- Writes new config files under configs/
5. Administrative Dashboard (dashboard.py)
- GUI to register customers, generate unique license, bundle installers (ZIP)
6. External Systems
- Lenel target application (receives simulated keystrokes)
- Customer’s file system (configs/, logs/, license cache)

- Hardware Interface → Decoder Module → Tray-Service → Autocomplete Engine → Lenel.
- Tray-Service ← Configuration Manager (config file read)
- Tray-Service ↔ License Manager (on-disk cache read/write)
- Tray-Service → Logging Subsystem
- Dashboard → License Manager (generate new license)
- Dashboard → ZIP-packager → Installer bundle

##### Architectural patterns & principles
- Monolithic service with modular internal subsystems
- Separation of concerns: decoding, configuration, licensing, UI, automation
- Plugin-style configs to allow field mapping/extensibility
- Single entry points: tray executable vs dashboard script

##### Technologies & frameworks
- Python 3.x, pyserial (COM port), custom XOR logic, pyautogui, standard logging library
- Batch script (compilar_dashboard.bat) for building dashboard executable
- ZIP utilities for installer generation

##### Final detail checklist
- Every subprocess: COM detection, XOR decoding, pyautogui automation, config creation, license validation, logging.
- How configs feed the tray service and how the dashboard writes configs and licenses.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Tray Service Layer
    subgraph "Runtime Tray Service"
        direction TB
        COMDetect["COM Port Detection Module"]:::core
        XORDecode["XOR Decoder Logic"]:::core
        DataExtract["Data Extraction Module"]:::core
        TrayApp["Tray-Service Application"]:::core
        ConfigMgr["Configuration Manager"]:::core
        AutoEngine["Autocomplete Engine (pyautogui)"]:::core
        LicenseMgr["License Manager"]:::core
        LogSub["Logging Subsystem"]:::core
        SysTrayUI["System Tray UI"]:::core
    end

    %% Administrative Dashboard Layer
    subgraph "Administrative Dashboard Tool"
        direction TB
        DashboardUI["Administrative Dashboard (Installer Generator UI)"]:::admin
        LicenseGen["License Generator"]:::admin
        ZIPPack["ZIP Packager"]:::admin
        TemplateMain["Config Template Generator Entry"]:::admin
        CrearConfig["Config Builder Routines"]:::admin
        Dependency["Dependency Manifest (requirements.txt)"]:::admin
    end

    %% External Systems and Data Stores
    subgraph "External & Storage"
        direction TB
        HWReader["Hardware ID/QR Reader"]:::external
        LenelApp["Lenel Target Application"]:::external
        FileSystem["Customer File System"]:::external
        ConfigStore[(Configs Directory)]:::datastore
        LogStore[(Logs Directory)]:::datastore
        LicenseCache[(License Cache)]:::datastore
        InstallerBundle[(Installer Bundle ZIP)]:::datastore
    end

    %% Runtime Tray Service Flows
    HWReader -->|"serial data"| COMDetect
    COMDetect -->|"raw payload"| XORDecode
    XORDecode -->|"decoded fields"| DataExtract
    DataExtract -->|"form data"| AutoEngine
    AutoEngine -->|"simulated keystrokes"| LenelApp

    ConfigMgr -->|"reads config"| ConfigStore
    TrayApp -->|"load modules"| ConfigMgr
    TrayApp -->|"invoke"| AutoEngine
    TrayApp -->|"validate license"| LicenseMgr
    LicenseMgr -->|"cache lookup"| LicenseCache
    TrayApp -->|"log event"| LogSub
    LogSub -->|"write entry"| LogStore
    SysTrayUI -->|"control"| TrayApp
    SysTrayUI -->|"switch config"| ConfigMgr
    SysTrayUI -->|"new config"| TemplateMain

    %% Administrative Dashboard Flows
    DashboardUI -->|"generate license"| LicenseGen
    LicenseGen -->|"write to cache"| LicenseCache
    DashboardUI -->|"run template entry"| TemplateMain
    TemplateMain -->|"call routines"| CrearConfig
    CrearConfig -->|"output new configs"| ConfigStore
    DashboardUI -->|"bundle installer"| ZIPPack
    ZIPPack -->|"produce"| InstallerBundle
    DashboardUI -->|"view dependencies"| Dependency

    %% Click Events
    click DashboardUI "https://github.com/andrick-dms/dms-automatedidreader/blob/main/DMS-AutomatedIDReader V3.2/dashboard.py"
    click Dependency "https://github.com/andrick-dms/dms-automatedidreader/blob/main/DMS-AutomatedIDReader V3.2/requirements.txt"
    click TemplateMain "https://github.com/andrick-dms/dms-automatedidreader/blob/main/DMS-AutomatedIDReader V3.2/template/main.py"
    click CrearConfig "https://github.com/andrick-dms/dms-automatedidreader/blob/main/DMS-AutomatedIDReader V3.2/template/crear_configuracion.py"
    click FileSystem "https://github.com/andrick-dms/dms-automatedidreader/tree/main/DMS-AutomatedIDReader V3.2/template/"

    %% Styles
    classDef core fill:#a6cee3,stroke:#1f78b4,color:#000
    classDef external fill:#b2df8a,stroke:#33a02c,color:#000
    classDef admin fill:#fdbf6f,stroke:#e31a1c,color:#000
    classDef datastore fill:#cab2d6,stroke:#6a3d9a,color:#000
```
