# allison-ggr/sdk-checador architecture

> Architecture diagram of the GitHub repository allison-ggr/sdk-checador, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allison-ggr/sdk-checador
- Repository: https://github.com/allison-ggr/sdk-checador

## Overview

##### Project Type and Purpose
- This is an open-source Python SDK and tooling suite for ZKTeco biometric attendance devices.
- It provides:
- A core Python library (`zk/`) implementing device communications (connect, get_users, get_attendance, set_user, backup/restore, etc.)
- A set of CLI/test scripts (e.g., `test_machine.py`, `test_backup_restore.py`, `basic_test.py`, `script_*.py`) that invoke the library to perform common tasks.
- Example scripts under `example/` showing API usage.
- A collection of static HTML/JS/CSS files (`vistashtml/`) representing a simple web dashboard/user interface.
- Documentation built with Sphinx in `docs/`.

##### File Structure Analysis
- Top‐level:
- `setup.py`, `.travis.yml`, GitHub config – packaging and CI.
- `zk/` – core library modules (attendance.py, user.py, finger.py, base.py, const.py, exception.py, scripphpjson.php).
- `example/` – standalone scripts demonstrating library usage.
- `*.py` scripts at root – assorted utilities for backup, restore, user/device management.
- `test_*.py` – unit/integration tests.
- `vistashtml/` – static front-end assets (HTML, JS, CSS) for a dashboard-like UI.
- `docs/` – Sphinx source for developer documentation.

##### Architecture Overview
- Main Components:
A. User Interfaces
1. CLI Tools & Scripts
2. Example Scripts
3. Static Web Dashboard (optional, file‐served or embedded in another server)
B. Core SDK
– ZK class and submodules (attendance, user, finger, exception, const)
– Network transport layer (TCP/UDP) for device communications
C. External Service
– ZKTeco attendance device(s) over LAN (IP+port)
D. Persistent Artifacts
– Backup files (`.bak`, `.json`)
– Logs and test outputs

##### Relationships & Data Flows
- Users (via CLI or Web UI) → invoke functions in the Core SDK
- Core SDK → serialize commands → send to Device over TCP/UDP
- Device → responds → Core SDK parses responses into objects (User, Attendance, Finger)
- Core SDK → returns objects/data to CLI or Web UI
- For backup/restore: Core SDK ↔ File system (read/write backup files, JSON)
- Tests/Examples → import Core SDK directly

##### Architectural Patterns & Design Principles
- Layered Design:
- Presentation (CLI / Web UI)
- Domain & API (Core SDK)
- Infrastructure (Network transport, File I/O)
- Single Responsibility: each script/tool has one focus (backup, restore, test machine, user management).
- Extensibility: modular subpackages (`attendance.py`, `user.py`, `finger.py`, etc.)
- Standard packaging (setup.py) and documentation (Sphinx)

##### Components & Technologies
- Python 2/3 compatibility (setup.py, pip packaging)
- Networking: socket-based TCP/UDP communication in `zk/base.py`
- Sphinx (`docs/`) for documentation
- Travis CI for continuous integration
- Static HTML/JS/CSS front-end (no backend, can be served by simple HTTP server)
- JSON for backup/restore payloads

##### Essential Elements
- Annotations for key protocols, data formats (JSON, templates, .bak)

## Diagram (Mermaid)

```mermaid
graph TD
    User["External User"]:::user

    subgraph "User Interfaces"
        CLI["CLI Tools & Scripts"]:::ui
        Example["Example Scripts"]:::ui
        Web["Static Web Dashboard"]:::ui
    end

    subgraph "Core SDK (pyzk library)"
        Attendance["attendance.py"]:::core
        UserMod["user.py"]:::core
        Finger["finger.py"]:::core
        Base["base.py"]:::core
        Const["const.py"]:::core
        ExceptionMod["exception.py"]:::core
        Init["__init__.py"]:::core
        PHPHelper["scripphpjson.php"]:::core
    end

    Device["ZKTeco Device(s)"]:::device

    FileSys["File System (Backup/Restore)"]:::storage

    Docs["Documentation (Sphinx)"]:::docs

    subgraph "Packaging & CI"
        Setup["setup.py"]:::infra
        CIYml[".travis.yml"]:::infra
    end

    User -->|"uses"| CLI
    User -->|"runs"| Example
    User -->|"views (optional)"| Web

    CLI -->|"imports"| Attendance
    CLI -->|"imports"| UserMod
    CLI -->|"imports"| Finger
    CLI -->|"imports"| Base
    CLI -->|"imports"| Const
    CLI -->|"imports"| ExceptionMod

    Example -->|"imports"| Attendance
    Example -->|"imports"| UserMod
    Example -->|"imports"| Finger
    Example -->|"imports"| Base

    Web -->|"calls SDK via HTTP file serve"| Base

    Attendance -->|"TCP/UDP port 4370"| Device
    UserMod -->|"TCP/UDP port 4370"| Device
    Finger -->|"TCP/UDP port 4370"| Device
    Base -->|"network transport"| Device

    Device -->|"responses"| Attendance
    Device -->|"responses"| UserMod
    Device -->|"responses"| Finger

    Attendance -->|"returns data"| CLI
    UserMod -->|"returns data"| CLI
    Finger -->|"returns data"| CLI

    Base -->|"reads/writes .json/.bak"| FileSys
    CLI -->|"backup/restore"| FileSys

    CoreSDKDocs["Sphinx build"]:::docs
    Base -->|"autogenerate docs"| CoreSDKDocs
    CoreSDKDocs -->|"outputs"| Docs

    Setup -->|"defines packaging"| CoreSDKDocs
    CIYml -->|"runs tests/docs build"| Setup

    classDef user fill:#EFEFEF,stroke:#000,stroke-width:1px
    classDef ui fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px
    classDef core fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef device fill:#FFE0B2,stroke:#F57C00,stroke-width:2px
    classDef storage fill:#ECEFF1,stroke:#90A4AE,stroke-width:2px
    classDef docs fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px
    classDef infra fill:#FFCCBC,stroke:#D84315,stroke-width:2px

    click CLI "https://github.com/allison-ggr/sdk-checador/blob/main/basic_test.py"
    click Example "https://github.com/allison-ggr/sdk-checador/tree/main/example/"
    click Web "https://github.com/allison-ggr/sdk-checador/tree/main/vistashtml/"
    click Attendance "https://github.com/allison-ggr/sdk-checador/blob/main/zk/attendance.py"
    click UserMod "https://github.com/allison-ggr/sdk-checador/blob/main/zk/user.py"
    click Finger "https://github.com/allison-ggr/sdk-checador/blob/main/zk/finger.py"
    click Base "https://github.com/allison-ggr/sdk-checador/blob/main/zk/base.py"
    click Const "https://github.com/allison-ggr/sdk-checador/blob/main/zk/const.py"
    click ExceptionMod "https://github.com/allison-ggr/sdk-checador/blob/main/zk/exception.py"
    click PHPHelper "https://github.com/allison-ggr/sdk-checador/blob/main/zk/scripphpjson.php"
    click Docs "https://github.com/allison-ggr/sdk-checador/tree/main/docs/"
    click Setup "https://github.com/allison-ggr/sdk-checador/blob/main/setup.py"
    click CIYml "https://github.com/allison-ggr/sdk-checador/blob/main/.travis.yml"
```
