# amoscardino/inky-desk architecture

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

- Interactive diagram: https://gitdiagram.com/amoscardino/inky-desk
- Repository: https://github.com/amoscardino/inky-desk

## Overview

##### A client component designed to run on a Raspberry Pi with an attached InkyWHAT screen.
2. A server component, written in C# (.NET), that can run either locally on the Raspberry Pi or remotely, provided it is accessible via HTTP.

There’s also a “stand” folder containing design files (.scad, .stl) for a physical stand, which suggests that the project covers both software and hardware (mechanical design) aspects for a complete solution.

- Client (Raspberry Pi with InkyWHAT Screen)
- This as a separate module.
- Components: InkyDesk client scripts (inkydesk.py and inkydesk.sh) and any local configuration mentioned in its README.
- That this script will be responsible for retrieving image/calendar data via HTTP calls and outputting it to the e-ink display.

- Server (Backend API)
▪ Configuration: Use of JSON files (calendars.json) and appsettings.json (with a development alternative) to control behavior.
▪ Models: Representing the data structures (CalendarModel, EventModel, ReplacementModel).
▪ Services: Business logic for calendars, events, images, replacements, and weather (CalendarService, EventService, ImageService, ReplacementsService, WeatherService).
▪ Utilities: Helper classes (e.g., RandomUtilities.cs) used across the server logic.
- Dockerfile, which indicates the server can be containerized for deployment.

- External Interactions:
- You may also mention any external APIs (for example, the WeatherService might fetch data from an external weather source) even if details aren’t fully specified.

- Stand Hardware (Optional Component)
- A block representing the design files for the physical stand. This shows the integration of the hardware dimension and how the software (the InkyDesk display) will be physically mounted.

B. Indicate Relationships and Data Flow:

- From the Client module to the Server module, indicating that the Raspberry Pi communicates with the server over HTTP (data requests, responses with rendered content).

- Separation of concerns:
- The client is solely responsible for interfacing with the e-ink display and sending/receiving HTTP requests.
- The server handles business logic and data management, reflecting an MVC-like structure (even if it’s not literally an MVC framework, the separation between Models and Services strongly implies layered architecture).

C. Identify Architectural Patterns and Technologies:

- Technology Stack:
- Client: Python scripts and shell scripts running on Raspberry Pi, specialized to interact with an InkyWHAT e-ink screen.
- Server: .NET (as indicated by InkyDesk.Server.csproj and C# files), containerized via Docker, with clear delineation between models, services, and utilities.
- Patterns:
- Service-oriented decomposition: especially within the server where each service (for calendar, events, images, etc.) encapsulates specific functionality.
- Configuration via JSON files, suggesting a dynamic and environment-oriented setup (different settings for development vs. production).

- Within the Client section:
- Files or functions (for example, inkydesk.py for the core logic, inkydesk.sh for deployment/launch).
- Within the Server section:
- Create subcomponents:
▪ Configuration: Represent appsettings.json and calendars.json.
▪ Utility Components: RandomUtilities and similar helper components.
- A note or a sidebar that mentions the Dockerfile for container deployment.
- For the External Interactions:
- Optionally, if the WeatherService interacts with an external weather API, denote with an additional module “External Weather API” and show the interaction.
- For the Stand hardware:

E. Design Elements and Legends:

- Rectangles for software components.

F. Tailoring Based on Project Type:

Since this is a full-stack application with both embedded (client) and server components:
- Separation between the client running on the Raspberry Pi (interfacing directly with hardware) and the server’s backend operations.
- HTTP API layer that decouples client and server, allowing the server to be hosted independently of the client’s physical deployment.
- To document any integration points, such as the potential external APIs for weather data, to give a complete picture of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Component
    subgraph "Raspberry Pi – InkyDesk Client"
        CP1["inkydesk.py"]:::client
        CP2["inkydesk.sh"]:::client
    end

    %% Server Component
    subgraph "Server (Backend API)"
        S1["Program.cs"]:::server
        S2["InkyDesk.Server.csproj"]:::server
        S3["Dockerfile"]:::server
        %% Configuration Files
        subgraph "Configuration"
            SC1["appsettings.json"]:::config
            SC2["appsettings.Development.json"]:::config
            SC3["calendars.json"]:::config
        end
        %% Models
        subgraph "Models"
            SM1["CalendarModel"]:::model
            SM2["EventModel"]:::model
            SM3["ReplacementModel"]:::model
        end
        %% Services
        subgraph "Services"
            SS1["CalendarService"]:::service
            SS2["EventService"]:::service
            SS3["ImageService"]:::service
            SS4["ReplacementsService"]:::service
            SS5["WeatherService"]:::service
        end
        %% Utilities
        subgraph "Utilities"
            SU1["RandomUtilities"]:::utility
        end
        %% Internal Relationships within Server
        S1 --> SC1
        S1 --> SC2
        S1 --> SC3
        S1 --> SM1
        S1 --> SM2
        S1 --> SM3
        S1 --> SS1
        S1 --> SS2
        S1 --> SS3
        S1 --> SS4
        S1 --> SS5
        S1 --> SU1
        %% External interaction from WeatherService
        SS5 -->|"calls"| EWAPI["External Weather API"]:::external
    end

    %% Stand Hardware Component
    subgraph "InkyDesk Stand Hardware"
        H1["inkydesk-stand.scad"]:::hardware
        H2["inkydesk-stand.stl"]:::hardware
    end

    %% External HTTP Interaction from Client to Server
    CP1 -->|"HTTP_API_calls"| S1

    %% Click Events - Client
    click CP1 "https://github.com/amoscardino/inky-desk/blob/main/client/inkydesk.py"
    click CP2 "https://github.com/amoscardino/inky-desk/blob/main/client/inkydesk.sh"

    %% Click Events - Server Entry and Project Files
    click S1 "https://github.com/amoscardino/inky-desk/blob/main/server/Program.cs"
    click S2 "https://github.com/amoscardino/inky-desk/blob/main/server/InkyDesk.Server.csproj"
    click S3 "https://github.com/amoscardino/inky-desk/tree/main/server/Dockerfile"

    %% Click Events - Server Configuration
    click SC1 "https://github.com/amoscardino/inky-desk/blob/main/server/appsettings.json"
    click SC2 "https://github.com/amoscardino/inky-desk/blob/main/server/appsettings.Development.json"
    click SC3 "https://github.com/amoscardino/inky-desk/blob/main/server/Config/calendars.json"

    %% Click Events - Server Models
    click SM1 "https://github.com/amoscardino/inky-desk/blob/main/server/Models/CalendarModel.cs"
    click SM2 "https://github.com/amoscardino/inky-desk/blob/main/server/Models/EventModel.cs"
    click SM3 "https://github.com/amoscardino/inky-desk/blob/main/server/Models/ReplacementModel.cs"

    %% Click Events - Server Services
    click SS1 "https://github.com/amoscardino/inky-desk/blob/main/server/Services/CalendarService.cs"
    click SS2 "https://github.com/amoscardino/inky-desk/blob/main/server/Services/EventService.cs"
    click SS3 "https://github.com/amoscardino/inky-desk/blob/main/server/Services/ImageService.cs"
    click SS4 "https://github.com/amoscardino/inky-desk/blob/main/server/Services/ReplacementsService.cs"
    click SS5 "https://github.com/amoscardino/inky-desk/blob/main/server/Services/WeatherService.cs"

    %% Click Events - Server Utilities
    click SU1 "https://github.com/amoscardino/inky-desk/blob/main/server/Utilities/RandomUtilities.cs"

    %% Click Events - Stand Hardware
    click H1 "https://github.com/amoscardino/inky-desk/blob/main/stand/inkydesk-stand.scad"
    click H2 "https://github.com/amoscardino/inky-desk/blob/main/stand/inkydesk-stand.stl"

    %% Styles
    classDef client fill:#ffefd5,stroke:#333,stroke-width:2px;
    classDef server fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef config fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef model fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef service fill:#afeeee,stroke:#333,stroke-width:2px;
    classDef utility fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
