# ariel-lindemann/calendar-tasks architecture

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

- Interactive diagram: https://gitdiagram.com/ariel-lindemann/calendar-tasks
- Repository: https://github.com/ariel-lindemann/calendar-tasks

## Overview

##### Project type and purpose
- This is a full-stack web application built around a FastAPI backend that generates .ics calendar files from user-supplied recurring appointment sequences, plus a minimal static HTML/JavaScript frontend.

##### File structure
- Top level:
- Dockerfile, .github/workflows: container build & CI.
- requirements.txt: Python dependencies (FastAPI, pydantic, ics-library, uvicorn).
- config.json: default calendar settings.
- app/:
- calendar-tasks.py: FastAPI app entrypoint (defines endpoints, mounts static files).
- generate_calendar.py: business logic to construct an .ics file.
- sequence.py: pydantic models & validation of input sequences.
- frontend/:
- index.html: static UI that posts JSON to `/generate_calendar` and triggers download.

##### README for additional insights
- Backend exposes POST `/generate_calendar` returning an .ics file, and serves the UI at `/frontend/index.html`.
- Supports Docker build & run.
- OpenAPI docs at `/docs`.

a. Components
1. User & Web Browser (client)
2. Frontend Static UI (index.html + JavaScript)
3. FastAPI Backend (calendar-tasks.py)
4. Sequence Validation Layer (sequence.py + pydantic)
5. Calendar Generation Module (generate_calendar.py + ics library)
6. Configuration Store (config.json)
7. Docker Container (runtime environment)
8. CI/CD Pipeline (GitHub Actions)
b. Relationships & Data Flow
- User → Browser → loads index.html from Backend.
- Browser → (POST JSON) → FastAPI `/generate_calendar`.
- FastAPI → pydantic models → validate & normalize sequences.
- Validated data + config.json → Calendar Generation Module creates .ics.
- Backend → streams .ics → Browser → triggers file download.
c. Architectural patterns & design principles
- Layered architecture: Presentation (static UI), API layer (FastAPI), Domain logic (validation + generation).
- Use of dependency injection in FastAPI for config.
- Stateless service: no database, no session storage.
- Dockerized micro-service style for easy deployment.
d. Key technologies & libraries
- FastAPI (web framework, routing, dependency injection)
- pydantic (input validation & parsing)
- python-ics or similar (ICS file building)
- Uvicorn (ASGI server)
- Docker (containerization)
- GitHub Actions (CI/CD)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External User
    Browser(("User Browser")):::external

    %% Static Frontend
    Static["Static Frontend\n(index.html + JS)"]:::static

    %% CI/CD Pipeline
    CI["GitHub Actions"]:::ci
    DockerfileNode["Dockerfile"]:::static

    %% Docker Container with Backend Components
    subgraph "Docker Container"
        APNode["FastAPI App\n(calendar-tasks.py)"]:::compute
        Seq["Sequence Validator\n(sequence.py)"]:::compute
        Gen["Calendar Generator\n(generate_calendar.py)"]:::compute
        Config["config.json"]:::config
    end

    %% Data Flows
    Browser -->|GET /frontend/index.html| Static
    Static -->|POST JSON /generate_calendar| APNode
    APNode -->|"validate sequence"| Seq
    Seq -->|"generate ICS"| Gen
    Config -.->|"injected config"| Gen
    Gen -->|".ics file stream"| Static

    %% CI/CD Flow
    CI -->|"build-docker-image.yml"| DockerfileNode
    DockerfileNode -->|"build image"| APNode

    %% Click Events
    click Static "https://github.com/ariel-lindemann/calendar-tasks/blob/master/frontend/index.html"
    click APNode "https://github.com/ariel-lindemann/calendar-tasks/blob/master/app/calendar-tasks.py"
    click Seq "https://github.com/ariel-lindemann/calendar-tasks/blob/master/app/sequence.py"
    click Gen "https://github.com/ariel-lindemann/calendar-tasks/blob/master/app/generate_calendar.py"
    click Config "https://github.com/ariel-lindemann/calendar-tasks/blob/master/config.json"
    click DockerfileNode "https://github.com/ariel-lindemann/calendar-tasks/tree/master/Dockerfile"
    click CI "https://github.com/ariel-lindemann/calendar-tasks/blob/master/.github/workflows/build-docker-image.yml"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef static fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#F0F8FF,stroke:#000,stroke-width:1px
    classDef ci fill:#F9E79F,stroke:#000,stroke-width:1px
```
