# vihdutta/canvascrafter architecture

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

- Interactive diagram: https://gitdiagram.com/vihdutta/canvascrafter
- Repository: https://github.com/vihdutta/canvascrafter

## Overview

##### Project type and purpose
- CanvasCrafter is an automation tool (a small full-stack-style web app and CLI utility) whose purpose is to generate and upload course pages to Canvas.
- It uses FastAPI (backend) to serve or orchestrate the build process, Tailwind-styled templates (frontend) to produce static HTML, YAML/Excel files as the data source, and Canvas’s REST API for upload.

##### File structure
Top-level:
- main.py – entry point (starts the FastAPI server or CLI).
- readme.MD – project description.
- .gitignore – excludes build artifacts.
Directories:
- files/backend – Python scripts that implement each step of the pipeline:
– build_html.py
– populate_weeks.py
– upload_to_canvas.py
– zip_built_htmls.py
- files/yaml – data source (images.yaml, learning_objectives.yaml, overview_statements.yaml, schedule.xlsx).
- templates – Jinja2 (or similar) HTML templates (index.html, me2024_template.html) styled with Tailwind.
- resources – static assets (logo, CSS, JS if any).

##### README
- Tech stack confirms the use of FastAPI for API/CLI orchestration and Tailwind for frontend templates.

##### Components & Their Interactions
a. Main Components
1. Data Source
– YAML files & schedule.xlsx (local file system)
2. Backend Orchestrator
– main.py (FastAPI app + CLI entrypoint)
3. Processing Modules (in files/backend)
– build_html.py: reads data, populates templates → static HTML
– populate_weeks.py: splits/generates pages per week
– zip_built_htmls.py: packages pages into .zip for manual download
– upload_to_canvas.py: calls Canvas REST API to push built pages
4. Templates & Static Assets
– templates/ (HTML + Tailwind CSS classes)
– resources/ (images, logo, CSS)
5. External Service
– Canvas API (authentication, course page endpoints)
b. Relationships & Data Flow
- User triggers main.py (HTTP request or CLI command)
- main.py invokes populate_weeks.py → build_html.py
- build_html.py loads YAML/Excel → renders templates → writes output HTML
- zip_built_htmls.py packages outputs
- upload_to_canvas.py pushes pages to Canvas
- Responses/Logs flow back to the user via FastAPI endpoints or console
c. Architectural Patterns / Principles
- Modular pipeline: each script is a separate processing stage
- MVC-style templating: data (Model) + Jinja templates (View) + orchestration code (Controller)
- Single responsibility per module, facilitating testing and extension
d. Key Technologies
- FastAPI (orchestration, optional UI)
- Python 3.x (scripts)
- Jinja2 (template engine)
- Tailwind CSS (styling)
- openpyxl / pandas (Excel reading)
- requests or httpx (Canvas API calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Source"
        DS1["images.yaml"]:::data
        DS2["learning_objectives.yaml"]:::data
        DS3["overview_statements.yaml"]:::data
        DS4["schedule.xlsx"]:::data
    end

    subgraph "Orchestrator Layer"
        OR["main.py"]:::orchestrator
    end

    subgraph "Backend Pipeline"
        PM1["populate_weeks.py"]:::processing
        PM2["build_html.py"]:::processing
        PM3["zip_built_htmls.py"]:::processing
        PM4["upload_to_canvas.py"]:::processing
    end

    subgraph "Templates & Assets"
        T1["index.html"]:::templates
        T2["me2024_template.html"]:::templates
        RES["resources/"]:::templates
    end

    subgraph "External Service"
        CANVAS["Canvas API"]:::external
    end

    subgraph "Project Files"
        DOC["readme.MD"]:::infra
        GIT[".gitignore"]:::infra
    end

    DS1 & DS2 & DS3 & DS4 -->|read data| OR
    OR -->|invoke populate_weeks| PM1
    PM1 -->|generate per-week data| PM2
    T1 -->|templates| PM2
    T2 -->|templates| PM2
    RES -->|static assets| PM2
    PM2 -->|static HTML| PM3
    PM2 -->|static HTML| PM4
    PM3 -->|ZIP artifact| OR
    PM4 -->|POST /api/courses/:id/pages| CANVAS
    CANVAS -->|response/logs| OR

    click DS1 "https://github.com/vihdutta/canvascrafter/blob/main/files/yaml/images.yaml"
    click DS2 "https://github.com/vihdutta/canvascrafter/blob/main/files/yaml/learning_objectives.yaml"
    click DS3 "https://github.com/vihdutta/canvascrafter/blob/main/files/yaml/overview_statements.yaml"
    click DS4 "https://github.com/vihdutta/canvascrafter/blob/main/files/yaml/schedule.xlsx"
    click OR "https://github.com/vihdutta/canvascrafter/blob/main/main.py"
    click PM1 "https://github.com/vihdutta/canvascrafter/blob/main/files/backend/populate_weeks.py"
    click PM2 "https://github.com/vihdutta/canvascrafter/blob/main/files/backend/build_html.py"
    click PM3 "https://github.com/vihdutta/canvascrafter/blob/main/files/backend/zip_built_htmls.py"
    click PM4 "https://github.com/vihdutta/canvascrafter/blob/main/files/backend/upload_to_canvas.py"
    click T1 "https://github.com/vihdutta/canvascrafter/blob/main/templates/index.html"
    click T2 "https://github.com/vihdutta/canvascrafter/blob/main/templates/me2024_template.html"
    click RES "https://github.com/vihdutta/canvascrafter/tree/main/resources/"
    click DOC "https://github.com/vihdutta/canvascrafter/blob/main/readme.MD"
    click GIT "https://github.com/vihdutta/canvascrafter/blob/main/.gitignore"

    classDef data fill:lightgreen,stroke:#333,stroke-width:1px
    classDef orchestrator fill:plum,stroke:#333,stroke-width:1px
    classDef processing fill:lightblue,stroke:#333,stroke-width:1px
    classDef templates fill:lemonchiffon,stroke:#333,stroke-width:1px
    classDef external fill:pink,stroke:#333,stroke-width:1px
    classDef infra fill:lightgray,stroke:#333,stroke-width:1px
```
