# ascominitiative/alpycadevice architecture

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

- Interactive diagram: https://gitdiagram.com/ascominitiative/alpycadevice
- Repository: https://github.com/ascominitiative/alpycadevice

## Overview

##### Project type and purpose
- This is an open-source Python SDK (framework) for building ASCOM Alpaca device drivers.
- Its core is a “server” (`device/app.py`) that hosts one or more device implementations (e.g., the sample Rotator) over the Alpaca HTTP API.
- It also ships a rich set of templates for generating skeleton drivers for all ASCOM device types, plus a suite of ConformU tests in the `thunder-tests` folder.

##### File structure
- Top-level:
- `device/` – core SDK modules and sample driver
- `templates/` – code skeletons for all ASCOM device types
- `docs/` – Sphinx documentation source
- `thunder-tests/` – HTTP collection tests for ConformU
- Key modules under `device/`:
- `app.py` – entry point and HTTP server
- `management.py` – driver registration and lifecycle
- `discovery.py` – mDNS/Alpaca service discovery
- `rotatordevice.py` & `rotator.py` – the sample device implementation
- `config.py` & `config.toml` – runtime settings
- `log.py` & `exceptions.py` – logging and error handling
- `setup.py` – package metadata
- No database or external queue – purely in-memory drivers with HTTP interface.

##### Extract insights from the README
- Purpose: “lightweight Python framework” for any ASCOM device over Alpaca.
- Features: built-in ConformU passing sample, plus boilerplate templates.
- Usage: run `device/app.py`→HTTP endpoints→client tools (SkySafari, SGP, ConformU).
- External dependencies: ASCOM Platform 7, ConformU test suite, and any Alpaca-speaking client (e.g., Cartes du Ciel).

##### Main components
a. Alpaca Server
- DeviceApp (HTTP server - `device/app.py`)
- Driver Manager (`device/management.py`)
- Service Discovery (`device/discovery.py`)
b. Device Implementations
- Rotator (sample: `rotator.py` + `rotatordevice.py`)
- Other skeletons (from `templates/…`)
c. Configuration & Logging
- Config loader (`config.py` + `config.toml`)
- Logging subsystem (`log.py`)
d. External Clients & Tools
- ConformU test runner (`thunder-tests`)
- Alpaca-speaking applications (SkySafari, SGP, etc.)
e. Documentation system (Sphinx in `docs/`) – shown as a peripheral component.

##### Relationships and interactions
- External Client → HTTP(S) → Alpaca Server (`app.py`)
- Server → Driver Manager → Selected Device Implementation → domain logic
- Server ↔ Config loader (on startup)
- Server → Logging
- Server → Service Discovery (mDNS announcements)
- ConformU tests behave like another external client
- Templates are offline code-generation artifacts (no runtime link, but important for extensibility)

##### Architectural patterns & design principles
- Modular layering:
- Presentation/API layer (`app.py` + HTTP routes)
- Management/Dispatcher layer (`management.py`)
- Device business logic layer (`rotator.py`, plus template-generated peers)
- Plugin-style extensibility: new devices drop in and register via the same driver manager.
- Configuration-first initialization: one central TOML file.
- No persistent storage: purely in-memory simulation unless extended.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients/Tests" 
        direction TB
        ClientApps["Client Apps (SkySafari, SGP)"]:::external
        ConformUTests["ConformU Tests"]:::external
    end

    %% Core Runtime Server
    subgraph "Core Runtime Server" 
        direction TB
        App["Alpaca HTTP Server<br/>(DeviceApp)"]:::core
        Management["Driver Manager"]:::core
        Discovery["Service Discovery<br/>(mDNS/Alpaca)"]:::core
        Config["Configuration Loader"]:::core
        Logging["Logging Subsystem"]:::core
        Exceptions["Error Handling/Exceptions"]:::core
        Setup["Package Metadata/Setup"]:::core
        SHR["Helper/Shared Routines (SHR)"]:::core
    end

    %% Device Plugins
    subgraph "Device Implementations (Plugins)"
        direction TB
        RotatorLogic["Rotator Business Logic"]:::plugin
        RotatorWrapper["Rotator ASCOM Interface Wrapper"]:::plugin
    end

    %% Offline Artifacts
    subgraph "Offline Artifacts" 
        direction TB
        Templates["Skeleton Templates"]:::offline
        Docs["Documentation (Sphinx Sources)"]:::offline
        DBBackup["ConformU Backup Data"]:::offline
    end

    %% Connections
    ClientApps -->|HTTP| App
    ConformUTests -->|HTTP| App
    App -->|on startup initialize| Config
    App -->|register drivers| Management
    App -->|log events| Logging
    App -->|handle errors| Exceptions
    App -->|announce services| Discovery
    Management -->|loads| RotatorLogic
    Management -->|registers| RotatorWrapper

    %% Click Events
    click App "https://github.com/ascominitiative/alpycadevice/blob/master/device/app.py"
    click Management "https://github.com/ascominitiative/alpycadevice/blob/master/device/management.py"
    click Discovery "https://github.com/ascominitiative/alpycadevice/blob/master/device/discovery.py"
    click Config "https://github.com/ascominitiative/alpycadevice/blob/master/device/config.py"
    click Logging "https://github.com/ascominitiative/alpycadevice/blob/master/device/log.py"
    click Exceptions "https://github.com/ascominitiative/alpycadevice/blob/master/device/exceptions.py"
    click Setup "https://github.com/ascominitiative/alpycadevice/blob/master/device/setup.py"
    click SHR "https://github.com/ascominitiative/alpycadevice/blob/master/device/shr.py"
    click RotatorLogic "https://github.com/ascominitiative/alpycadevice/blob/master/device/rotator.py"
    click RotatorWrapper "https://github.com/ascominitiative/alpycadevice/blob/master/device/rotatordevice.py"
    click Templates "https://github.com/ascominitiative/alpycadevice/tree/master/templates/"
    click ConformUTests "https://github.com/ascominitiative/alpycadevice/tree/master/thunder-tests/collections/"
    click DBBackup "https://github.com/ascominitiative/alpycadevice/tree/master/thunder-tests/_db-backup/"
    click Docs "https://github.com/ascominitiative/alpycadevice/tree/master/docs/"

    %% Styling
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef plugin fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef offline fill:#D3D3D3,stroke-dasharray: 5 5,stroke:#000
```
