How darrenmcewan/birthday-ics-tool works
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.