# teodorviktor/tlsbot architecture

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

- Interactive diagram: https://gitdiagram.com/teodorviktor/tlsbot
- Repository: https://github.com/teodorviktor/tlsbot

## Overview

1. **Purpose of the repo**
   - This is a Python automation bot that uses Selenium to monitor TLS Contact for available appointment slots.
   - The architecture is very small and centered around a single automation workflow rather than multiple cooperating services.

2. **Core runtime**
   - The application is Python-based and depends on Selenium plus other packages listed in `requirements.txt`.
   - The bot likely runs as a command-line/background process, with browser automation doing the actual work against the TLS Contact website.

3. **Main application entry points**
   - `main.py` appears to be the primary bot runner.
   - `simpleserver.py` suggests an optional lightweight server process, likely used for keeping the app alive, exposing a status endpoint, or supporting deployment environments that expect a web process.
   - `start.sh` is the shell wrapper for launching the app in the target runtime environment.

4. **Configuration and shared state**
   - `variables.py` is the main configuration boundary for the project.
   - This file likely holds URLs, credentials, selectors, polling intervals, or other constants needed by the Selenium workflow.
   - Centralizing these values keeps the automation logic separate from environment-specific settings.

5. **Automation flow**
   - The bot’s main data flow is: start process → configure variables → launch browser automation → navigate TLS Contact pages → inspect availability → act or report based on appointment presence.
   - The repo does not show a persistent database or queue, so state is probably ephemeral and held in memory during each run.

6. **External dependency boundary**
   - The dominant external dependency is the TLS Contact website itself.
   - Selenium acts as the integration layer between the Python code and the browser, making browser behavior and site structure part of the system’s operational boundary.

7. **Deployment/runtime support**
   - `start.sh` indicates the bot is intended to be started in a controlled environment, possibly a container or hosted process platform.
   - `simpleserver.py` may exist to satisfy platform requirements for an always-on port or to support health checks.

8. **CI/CD and validation**
   - `.github/workflows/main.yml` and `.github/workflows/python-app.yml` show GitHub Actions is used for automation around the repository.
   - These workflows likely run lint/tests or basic validation on pushes and pull requests, but the repo tree does not suggest a complex release pipeline.

9. **Project structure boundaries**
   - There is no evidence of a layered backend, frontend, or microservice setup.
   - The project is essentially split into: automation logic, configuration, launch scripts, and CI configuration.

10. **Important architectural characteristic**
   - This is a browser-driven scraper/checker, not a traditional API service.
   - The most important operational concerns are browser startup, site interaction reliability, and resilience to page or selector changes.

11. **What to show in an architecture diagram**
   - A single Python bot process at the center.
   - Selenium/browser automation as the execution engine.
   - TLS Contact as the external system being checked.
   - `variables.py` as the configuration source.
   - `start.sh` and GitHub Actions as deployment/automation support around the core bot.

Main entry points: [`main.py`](https://github.com/teodorviktor/tlsbot/blob/main/main.py) (Bot runner), [`variables.py`](https://github.com/teodorviktor/tlsbot/blob/main/variables.py) (Variables), [`requirements.txt`](https://github.com/teodorviktor/tlsbot/blob/main/requirements.txt) (Dependencies), [`simpleserver.py`](https://github.com/teodorviktor/tlsbot/blob/main/simpleserver.py) (Simple server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Bot runner<br/>python entrypoint<br/>[main.py]"]
  node_browser{{"Selenium flow<br/>automation core"}}
  node_config["Variables<br/>config<br/>[variables.py]"]
end

subgraph group_support["Support"]
  node_server["Simple server<br/>optional runtime<br/>[simpleserver.py]"]
  node_launcher["Start script<br/>shell launcher<br/>[start.sh]"]
  node_deps["Dependencies<br/>python deps<br/>[requirements.txt]"]
  node_ci1["CI workflow A<br/>github actions<br/>[main.yml]"]
  node_ci2["CI workflow B<br/>github actions<br/>[python-app.yml]"]
end

subgraph group_external["External"]
  node_tls(("TLS Contact<br/>external site"))
end

node_launcher -->|"starts"| node_main
node_main -->|"reads"| node_config
node_main -->|"uses"| node_deps
node_main -->|"drives"| node_browser
node_browser -->|"checks"| node_tls
node_config -->|"configures"| node_browser
node_server -.->|"supports"| node_main
node_ci1 -.->|"validates"| node_main
node_ci2 -.->|"validates"| node_deps

click node_main "https://github.com/teodorviktor/tlsbot/blob/main/main.py"
click node_config "https://github.com/teodorviktor/tlsbot/blob/main/variables.py"
click node_server "https://github.com/teodorviktor/tlsbot/blob/main/simpleserver.py"
click node_launcher "https://github.com/teodorviktor/tlsbot/blob/main/start.sh"
click node_deps "https://github.com/teodorviktor/tlsbot/blob/main/requirements.txt"
click node_ci1 "https://github.com/teodorviktor/tlsbot/blob/main/.github/workflows/main.yml"
click node_ci2 "https://github.com/teodorviktor/tlsbot/blob/main/.github/workflows/python-app.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_browser,node_config toneBlue
class node_server,node_launcher,node_deps,node_ci1,node_ci2 toneAmber
class node_tls toneMint
```

## Components

### Application

Core bot and runtime entrypoints

- [Bot runner](https://github.com/teodorviktor/tlsbot/blob/main/main.py): python entrypoint · Primary automation process that drives the appointment checks. · `main.py`
- **Selenium flow**: automation core · Browser-driven workflow for logging in, navigating pages, and checking slot availability.
- [Variables](https://github.com/teodorviktor/tlsbot/blob/main/variables.py): config · Shared configuration and constants used by the automation logic. · `variables.py`

### Support

Deployment and CI scaffolding

- [Simple server](https://github.com/teodorviktor/tlsbot/blob/main/simpleserver.py): optional runtime · Lightweight process used for hosting or keeping the app alive in deployment. · `simpleserver.py`
- [Start script](https://github.com/teodorviktor/tlsbot/blob/main/start.sh): shell launcher · Shell wrapper used to start the bot in the target environment. · `start.sh`
- [Dependencies](https://github.com/teodorviktor/tlsbot/blob/main/requirements.txt): python deps · Python package boundary defining Selenium and related runtime libraries. · `requirements.txt`
- [CI workflow A](https://github.com/teodorviktor/tlsbot/blob/main/.github/workflows/main.yml): github actions · One of the repository automation workflows for validation on GitHub Actions. · `.github/workflows/main.yml`
- [CI workflow B](https://github.com/teodorviktor/tlsbot/blob/main/.github/workflows/python-app.yml): github actions · Additional GitHub Actions workflow for repository checks or Python validation. · `.github/workflows/python-app.yml`

### External

Outside systems the bot depends on

- **TLS Contact**: external site · Target website where the bot checks for appointment availability.

## Connections

- Start script → Bot runner: starts · Launches the primary bot process.
- Bot runner → Variables: reads · Loads shared variables and runtime settings.
- Bot runner → Dependencies: uses · Runs with the repository's Python dependency set.
- Bot runner → Selenium flow: drives · Delegates the appointment-checking workflow to browser automation.
- Selenium flow → TLS Contact: checks · Interacts with the TLS Contact website to inspect availability.
- Variables → Selenium flow: configures · Provides URLs, selectors, and other automation constants.
- Simple server → Bot runner: supports · Can be used as a companion process for deployment/runtime expectations.
- CI workflow A → Bot runner: validates · Automated repository checks exercise the bot code path.
- CI workflow B → Dependencies: validates · GitHub Actions checks the Python environment and package setup.
