# gbarroslimajr/cita_tie architecture

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

- Interactive diagram: https://gitdiagram.com/gbarroslimajr/cita_tie
- Repository: https://github.com/gbarroslimajr/cita_tie

## Overview

##### Project type and purpose
- This is a CLI-based automation tool (not a full-stack web app).
- Its sole responsibility is to automate the process of checking and booking appointments (“agendamento”) on the Spanish extranjería website, repeating until success and optionally issuing audio notifications.

##### File structure
- Top-level files:
- run.sh (shell wrapper for ease of execution)
- cita_tie.py (the main Python automation script)
- resources/ (media files for success/failure sounds)
- Config/build/deployment files:
- README.md, LICENSE, .gitignore
- No database or frontend separately—everything runs locally via Python/Selenium.

##### Architecture overview from the README
- Core technologies: Python 3.x, Selenium WebDriver, ChromeDriver, Bash
- Key Python modules:
- argparse (CLI parameter parsing)
- selenium + webdriver_manager (browser automation & driver management)
- logging (event recording)
- Execution flow:
1. User invokes run.sh with flags
2. run.sh launches cita_tie.py with arguments
3. Script uses WebDriverManager to install/locate ChromeDriver
4. Selenium drives a Chrome instance (headless if requested)
5. Script navigates to target site, fills forms, checks availability, loops
6. On each iteration logs status; on success/failure plays corresponding MP4 via OS call

##### Main components & interactions (
A. User Layer
– run.sh (Bash CLI)
– CLI arguments passed to Python

B. Automation Engine (Python)
– Argument Parser (argparse)
– Logging Module
– Scheduler/Loop Controller (handles retry intervals)
– Notification Module (invokes resource media)

C. WebDriver Subsystem
– webdriver_manager: Driver installer/resolver
– ChromeDriver executable
– Chrome Browser instance (headful or headless)

D. External Service
– Extranjería Website (HTTP(S) over the Internet)

E. Resources
– success.mp4 / failure.mp4 (audio notifications)

##### Relationships & data flow
1. User → run.sh: supplies parameters
2. run.sh → Python Script: spawns cita_tie.py process
3. Python Script → webdriver_manager: locate/install ChromeDriver
4. Python Script → ChromeDriver: start browser session
5. Browser → Extranjería Site: HTTP requests to navigate/forms
6. Extranjería → Browser → Selenium → Python: page state & availability
7. Python → Notification Module → OS: play success/failure media
8. Python → Logging Module → local log output

##### Architectural patterns & design principles
- Single-responsibility modules: parsing, scheduling, notification, logging
- Orchestration pattern: central script coordinating sub-components
- Retries with back-off interval: basic scheduler design

##### Essential elements
- Labels on every component (e.g., “Scheduler”, “Notification Module”)
- Executable scripts
- Modules
- External systems
- Media resources

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        CLI["run.sh"]:::cli
    end

    subgraph "Automation Engine"
        ORCH["cita_tie.py"]:::engine
        ARG["Argument Parser"]:::engine
        LOG["Logging Module"]:::engine
        SCH["Scheduler/Loop Controller"]:::engine
        NOTIF["Notification Module"]:::engine
        WM["WebDriver Manager Integration"]:::engine
    end

    subgraph "WebDriver Subsystem"
        WDM["WebDriver Manager"]:::wd
        CHRDRV["ChromeDriver"]:::wd
        BROWSER["Chrome Browser Instance"]:::wd
    end

    subgraph "External Service"
        EXTERN["Extranjería Website"]:::external
    end

    subgraph "Resources"
        RES["resources/"]:::res
        SUC["success.mp4"]:::res
        FAIL["failure.mp4"]:::res
    end

    CLI -->|"invokes"| ORCH
    ORCH --> ARG
    ORCH --> LOG
    ORCH --> SCH
    ORCH --> NOTIF
    ORCH --> WM

    WM -->|"install/locate"| WDM
    WDM -->|"provides driver"| CHRDRV
    CHRDRV -->|"launches"| BROWSER
    BROWSER -->|"HTTP requests"| EXTERN
    EXTERN -->|"responses"| BROWSER
    BROWSER -->|"page state"| ORCH

    SCH -.->|"retry loop"| WM

    NOTIF -->|"play success"| SUC
    NOTIF -->|"play failure"| FAIL

    click CLI "https://github.com/gbarroslimajr/cita_tie/blob/main/run.sh"
    click ORCH "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click ARG "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click LOG "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click SCH "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click NOTIF "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click WM "https://github.com/gbarroslimajr/cita_tie/blob/main/cita_tie.py"
    click RES "https://github.com/gbarroslimajr/cita_tie/tree/main/resources/"
    click SUC "https://github.com/gbarroslimajr/cita_tie/blob/main/resources/sucess.mp4"
    click FAIL "https://github.com/gbarroslimajr/cita_tie/blob/main/resources/failure.mp4"

    class CLI cli
    class ORCH,ARG,LOG,SCH,NOTIF,WM engine
    class WDM,CHRDRV,BROWSER wd
    class EXTERN external
    class RES,SUC,FAIL res

    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px
    classDef engine fill:#98fb98,stroke:#000,stroke-width:1px
    classDef wd fill:#ffa500,stroke:#000,stroke-width:1px
    classDef external fill:#ff6347,stroke:#000,stroke-width:1px
    classDef res fill:#ffff99,stroke:#000,stroke-width:1px
```
