How ariel-lindemann/calendar-tasks works
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)