# darrenmcewan/birthday-ics-tool architecture

> Architecture diagram of the GitHub repository darrenmcewan/birthday-ics-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darrenmcewan/birthday-ics-tool
- Repository: https://github.com/darrenmcewan/birthday-ics-tool

## Overview

##### Project type & purpose (from README + file tree)

This is a **static, client-side web application** (no backend) that:
- Accepts a **CSV file** with birthday data
- Parses and maps columns (name, birthdate, note)
- Generates an **ICS calendar file** (recurring birthday events up to a max age)
- Triggers an **in-browser download**
- Emphasizes **privacy**: “Everything runs in your browser”

**Evidence from structure**
- `index.html` = single-page UI entrypoint
- `css/style.css` = presentation
- `js/app.js` = all application logic (parsing, settings, ICS generation, download)
- No `package.json`, no server code, no build system → likely “vanilla” HTML/CSS/JS

##### How to read the file structure into architectural components

Given:
- `index.html`: UI shell (file input, settings, preview, download CTA)
- `js/app.js`: the “application core” containing multiple conceptual modules even if physically in one file

- CSV ingestion (File input)
- CSV parsing (delimiter handling, line splitting, quoting if any)
- Column mapping (UI-driven mapping to fields)
- Date parsing/normalization (DD/MM/YYYY vs other formats)
- Business rules (max age → recurrence/end date strategy)
- ICS generation (VEVENT construction)
- Preview rendering (first 10 rows)
- Download/export (Blob + object URL + auto download)

##### Runtime boundary
**Single boundary:** “User’s Browser (Client-Side App)”

- **UI Layer** (index.html + CSS)
- **App Logic** (js/app.js split into modules)

- **User** (interacts via file picker and settings)
- **Local File System** (CSV source file; ICS output download destination)
- Optionally: **Calendar App** (Google Calendar/Apple Calendar/Outlook) as a consumer of the exported `.ics`

##### CSV Import & Parse
- FileReader / file loading
- Delimiter selection & parsing
- Row validation (required fields)

##### Mapping & Validation
- CSV headers → (name, birthdate, note)
- Required field checks
- Error reporting to UI

##### Date Normalization
- Parse birthdate based on selected format
- Produce normalized date object/ISO representation

##### Event Rules Engine
- Recurrence
- Apply “max age” rule (how many occurrences / until date)

##### ICS Builder
- Create VCALENDAR
- For each row create VEVENT
- Inject summary/description (name + note)
- Serialize to `.ics` text

##### Export / Download
- Blob creation
- Object URL
- Auto-download via anchor click
- Filename strategy (optional)

##### External Consumer (Optional)
- Calendar Application imports `.ics`

##### User → UI
- “Select CSV file”
- “Choose delimiter/date format/max age”
- “Map columns”
- “Click download”

##### UI → CSV Import
- “File object”

##### CSV Import → CSV Parse
- “Raw CSV text”

##### CSV Parse → Mapping & Validation
- “Parsed rows + headers”

##### Mapping & Validation → UI
- “Preview rows (first 10)”
- “Validation errors / warnings”

##### Mapping & Validation → Date Normalization
- “Birthdate strings + selected format”

##### Date Normalization → Event Rules Engine
- “Normalized birthdate + max age”

##### Event Rules Engine → ICS Builder
- “Event model(s): name, dates, recurrence rules, note”

##### ICS Builder → Export
- “ICS text”

##### Export → Local File System
- “Downloaded .ics file”

##### Local File System → Calendar App
- “User imports .ics”

This is essentially a **data transformation pipeline** with UI feedback loops.

##### Architectural patterns/principles to highlight (specific to this project)

- **Pipeline architecture**: CSV → normalized model → ICS serialization
- **Privacy-first boundary**: keep all data inside the browser boundary; the only I/O is local read and local download

- Actor: User
- System: “CSV to ICS Converter (Browser App)”
- External systems: Local file system, Calendar app
- No server / no cloud

Inside “Browser App”, show:
- UI
- CSV Parser
- Column Mapper/Validator
- Date Parser
- Recurrence/Rules
- ICS Generator
- Download/Exporter

**External:**
- [User]
- [Local File System]
- [Calendar App]

**Boundary: Browser**
- [index.html UI]
- file input
- settings
- mapping UI
- preview
- download button
- [app.js Application Core]
- CSV Import (FileReader)
- CSV Parse (delimiter)
- Column Mapping & Validation
- Date Normalization
- Recurrence Rules (max age)
- ICS Builder (VCALENDAR/VEVENT)
- Export/Download (Blob + URL)

**Flows:**
- User selects CSV → Browser reads local file
- Parsed preview → UI
- Generate ICS → download to local FS
- User imports into calendar app

A small callout: “All processing happens locally in browser; no network requests.”

That’s the most accurate “system design” representation for this repo: a **self-contained browser pipeline** with clear internal components and explicit I/O boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram 1: Context (C4 L1)
  %% =========================================================
  subgraph "Context (C4 Level 1)"
    direction TB

    U["User"]:::external
    FS[("Local File System")]:::external
    CAL["Calendar App\n(Google/Apple/Outlook)"]:::external

    subgraph "User's Browser (Client-Side)"
      direction TB
      SYS["CSV → ICS Converter\n(Static Browser App)"]:::system
      NOTE["Note: All processing happens locally.\nNo backend / no network requests."]:::note
    end

    U -->|"selects_CSV_file"| FS
    U -->|"uses_app_UI"| SYS
    SYS -->|"reads_file_via_File_API"| FS
    SYS -->|"downloads_.ics"| FS
    FS -->|"user_imports_.ics"| CAL
  end

  %% =========================================================
  %% Diagram 2: Container/Component (C4 L2/3 hybrid)
  %% =========================================================
  subgraph "Container/Component (C4 Level 2/3 Hybrid)"
    direction TB

    U2["User"]:::external
    FS2[("Local File System")]:::external
    CAL2["Calendar App\n(ICS Importer)"]:::external

    subgraph "Browser (Client-Side App Boundary)"
      direction TB

      subgraph "UI Layer"
        direction TB
        UI["UI / Presentation\n(index.html)\n- File picker\n- Settings (delimiter/date/max age)\n- Column mapping controls\n- Preview (first 10)\n- Download CTA"]:::ui
        CSS["UI Styling / Assets\n(css/style.css)"]:::asset
      end

      subgraph "Application Core (js/app.js)"
        direction TB

        CORE["Client-Side Pipeline Orchestrator\n(js/app.js)"]:::core

        IMP["CSV Import\n(FileReader API)"]:::logic
        PARSE["CSV Parsing\n(delimiter,row_split,quoting)"]:::logic
        MAP["Column Mapping & Validation\n(header→fields,required_checks,errors)"]:::logic
        DATE["Date Normalization\n(parse selected format → normalized date)"]:::logic
        RULES["Event Rules Engine\n(max_age → recurrence/until)"]:::logic
        ICS["ICS Builder / Generator\n(VCALENDAR + VEVENT serialization)"]:::logic
        EXP["Export / Download\n(Blob + ObjectURL + auto-download)"]:::logic
      end
    end

    %% External interactions
    U2 -->|"selects_CSV_file"| FS2
    U2 -->|"configures_settings_and_mapping"| UI
    UI -->|"File_object"| IMP
    IMP -->|"raw_CSV_text"| PARSE
    PARSE -->|"parsed_headers_and_rows"| MAP

    %% UI feedback loop
    MAP -->|"preview_rows_(first_10)"| UI
    MAP -->|"validation_errors_warnings"| UI

    %% Transformation pipeline
    MAP -->|"birthdate_strings_and_format"| DATE
    DATE -->|"normalized_birthdate_and_max_age"| RULES
    RULES -->|"event_models_(name,dates,rrule,note)"| ICS
    ICS -->|"ICS_text_string"| EXP
    EXP -->|"downloaded_.ics_file"| FS2
    FS2 -->|"user_imports_.ics"| CAL2

    %% Internal orchestration links
    CORE -->|"orchestrates"| IMP
    CORE -->|"orchestrates"| PARSE
    CORE -->|"orchestrates"| MAP
    CORE -->|"orchestrates"| DATE
    CORE -->|"orchestrates"| RULES
    CORE -->|"orchestrates"| ICS
    CORE -->|"orchestrates"| EXP

    %% UI composition
    UI ---|"styled_by"| CSS
  end

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click UI "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/index.html"
  click CSS "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/css/style.css"

  click CORE "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click IMP "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click PARSE "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click MAP "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click DATE "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click RULES "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click ICS "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click EXP "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/js/app.js"
  click NOTE "https://github.com/darrenmcewan/birthday-ics-tool/blob/main/README.md"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
  classDef system fill:#CBD5E1,stroke:#334155,color:#0F172A,stroke-width:2px
  classDef ui fill:#DBEAFE,stroke:#1D4ED8,color:#0B1F4B,stroke-width:1.5px
  classDef asset fill:#BFDBFE,stroke:#2563EB,color:#0B1F4B,stroke-width:1.5px
  classDef core fill:#93C5FD,stroke:#1D4ED8,color:#0B1F4B,stroke-width:2px
  classDef logic fill:#DCFCE7,stroke:#16A34A,color:#052E16,stroke-width:1.5px
  classDef note fill:#FEF3C7,stroke:#D97706,color:#3B2F0B,stroke-width:1.5px
```
