# sco1/skyportal architecture

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

- Interactive diagram: https://gitdiagram.com/sco1/skyportal
- Repository: https://github.com/sco1/skyportal

## Overview

##### Main Components

a. Hardware Layer:
- PyPortal Device (Central component)
- /Touchscreen Interface
- WiFi Module

b. Software Components:
- Core Application Modules (skyportal/)
- aircraftlib.py (Aircraft data handling)
- displaylib.py (Display management)
- maplib.py (Map rendering)
- networklib.py (Network communications)

c. External Services:
- Adafruit IO (Time lookup & image hosting)
- Geoapify (Static mapping)
- Aircraft Data Sources:
- OpenSky Network API
- ADSB.lol API
- Custom Proxy API (Optional)

**[External Services Layer]**
- ↕
**[Network Layer]**
- ↕
**[Application Layer]**
- ↕
**[Hardware Layer]**

##### Specific Implementation Details

- Rectangles: Core system components
- Clouds: External services
- Hexagons: Hardware components

- Blue: Core application components
- Green: External services
- Orange: Hardware components
- Purple: Network components

##### Key Relationships to Highlight

a. Data Flow:
- External APIs → Network Layer → Application Processing → Display
- Touch Input → Display Controller → Application Logic → Data Requests

b. Component Interactions:
- Tile generation/caching system
- Aircraft state processing pipeline
- Touch event handling system

##### Critical Elements

a. Memory Management:
- Filesystem cache for map tiles
- RAM constraints handling

b. Configuration Systems:
- secrets.py integration
- skyportal_config.py settings

c. Library Dependencies:
- CircuitPython core libraries
- Adafruit support libraries

##### The touch interface interaction flow

- Data flow directions
- Component types
- State indicators
- API endpoints

Keep in mind the project's constraints:
- Memory limitations of PyPortal
- Blocking nature of web requests
- Single-touch event handling

Remember to include error handling paths and the boot process modification for filesystem caching, as these are critical to the system's operation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef hardware fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef software fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef external fill:#98FB98,stroke:#333,stroke-width:2px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef assets fill:#F0E68C,stroke:#333,stroke-width:2px
    classDef lib fill:#B8860B,stroke:#333,stroke-width:2px

    %% External Services Layer
    subgraph ExternalServices
        AdafruitIO["Adafruit IO"]:::external
        Geoapify["Geoapify Maps"]:::external
        OpenSky["OpenSky Network"]:::external
        ADSB["ADSB.lol"]:::external
        ADSBProxy["ADSB.lol Proxy"]:::external
    end
    click ADSBProxy "https://github.com/sco1/skyportal/blob/main/adsblol-proxy/adsblol_proxy.py"

    %% Network Layer
    subgraph NetworkLayer
        NetworkLib["Network Communications"]:::software
        ConnManager["Connection Manager"]:::lib
        HTTPRequests["HTTP Requests"]:::lib
        IOLib["Adafruit IO Client"]:::lib
    end
    click NetworkLib "https://github.com/sco1/skyportal/blob/main/skyportal/networklib.py"
    click ConnManager "https://github.com/sco1/skyportal/blob/main/lib/adafruit_connection_manager.mpy"
    click HTTPRequests "https://github.com/sco1/skyportal/blob/main/lib/adafruit_requests.mpy"
    click IOLib "https://github.com/sco1/skyportal/blob/main/lib/adafruit_io/adafruit_io.mpy"

    %% Application Layer
    subgraph AppLayer
        Boot["Boot Process"]:::config
        MainApp["Main Application"]:::software
        Config["System Configuration"]:::config
        Secrets["Secrets Management"]:::config
        
        subgraph CoreModules
            AircraftLib["Aircraft Data Handler"]:::software
            DisplayLib["Display Manager"]:::software
            MapLib["Map Renderer"]:::software
        end
        
        subgraph Assets
            AircraftIcons["Aircraft Icons"]:::assets
            HeliIcons["Helicopter Icons"]:::assets
            DefaultMap["Default Map"]:::assets
            LocationMarkers["Location Markers"]:::assets
            StartupMedia["Startup Media"]:::assets
        end
    end
    click Boot "https://github.com/sco1/skyportal/blob/main/boot.py"
    click MainApp "https://github.com/sco1/skyportal/blob/main/code.py"
    click Config "https://github.com/sco1/skyportal/blob/main/skyportal_config.py"
    click Secrets "https://github.com/sco1/skyportal/blob/main/secrets.py"
    click AircraftLib "https://github.com/sco1/skyportal/blob/main/skyportal/aircraftlib.py"
    click DisplayLib "https://github.com/sco1/skyportal/blob/main/skyportal/displaylib.py"
    click MapLib "https://github.com/sco1/skyportal/blob/main/skyportal/maplib.py"
    click AircraftIcons "https://github.com/sco1/skyportal/blob/main/assets/airplane_icons.bmp"
    click HeliIcons "https://github.com/sco1/skyportal/blob/main/assets/heli_icons.bmp"
    click DefaultMap "https://github.com/sco1/skyportal/blob/main/assets/default_map.bmp"
    click LocationMarkers "https://github.com/sco1/skyportal/blob/main/assets/green_dot.bmp"
    click StartupMedia "https://github.com/sco1/skyportal/blob/main/pyportal_startup.bmp"

    %% Hardware Layer
    subgraph HardwareLayer
        PyPortal["PyPortal Device"]:::hardware
        Display["Display/Touchscreen"]:::hardware
        WiFi["WiFi Module"]:::hardware
        
        subgraph HardwareLibs
            PyPortalLib["PyPortal Interface"]:::lib
            TouchLib["Touchscreen Controller"]:::lib
            DisplayText["Display Text Handler"]:::lib
            DisplayShapes["Display Shapes"]:::lib
        end
        
        subgraph PhysicalHardware
            MountPlate["Mounting Plate"]:::hardware
            TowerLegs["Tower Legs"]:::hardware
            TowerOffice["Tower Office"]:::hardware
        end
    end
    click PyPortalLib "https://github.com/sco1/skyportal/tree/main/lib/adafruit_pyportal/"
    click TouchLib "https://github.com/sco1/skyportal/blob/main/lib/adafruit_touchscreen.mpy"
    click DisplayText "https://github.com/sco1/skyportal/tree/main/lib/adafruit_display_text/"
    click DisplayShapes "https://github.com/sco1/skyportal/tree/main/lib/adafruit_display_shapes/"
    click MountPlate "https://github.com/sco1/skyportal/blob/main/CAD/mounting_plate.STL"
    click TowerLegs "https://github.com/sco1/skyportal/blob/main/CAD/tower_legs.STL"
    click TowerOffice "https://github.com/sco1/skyportal/blob/main/CAD/tower_office.STL"

    %% Connections
    ExternalServices --> NetworkLayer
    NetworkLayer --> AppLayer
    AppLayer --> HardwareLayer
    Display --> AppLayer
    
    %% Legend
    subgraph Legend
        H["Hardware Component"]:::hardware
        S["Software Component"]:::software
        E["External Service"]:::external
        C["Configuration"]:::config
        A["Asset"]:::assets
        L["Library"]:::lib
    end
```
