How anghkooey/uafm_ical works
<explanation>
1. Project type and purpose
- This is a standalone CLI/open‑source Python tool whose sole responsibility is to import events from a local ICS file into Google Calendar (either an existing calendar or one it creates). It also offers an “edit” mode to adjust event time zones before import.
2. File‐structure analysis
- Top‐level modules and files:
• main.py – the entry point for both ics_import and ics_edit functions
• requirements.txt – Python dependencies (gcsa, ics, pytz)
• docs/ – multilingual documentation (PL, UA, EN icons, usage screenshots)
• .old/ – legacy code (csv.py), can be ignored in current design
• README.md, LICENSE, .gitignore – meta, no runtime impact
3. Key insights from README
- Core components described: ICS parsing, Google Calendar API integration via gcsa, OAuth2 credential management, event cleanup (delete >30‑day‐old), color assignment logic.
- No database or UI server; pure script + external API.
4. Main components for the system diagram
a. Input source
• ICS file (downloaded from university link or provided manually)
b. Processor modules (in main.py)
• ICS Parser (uses ics library)
• Event Transformer (applies time‐zone adjustment, color logic via a COLORS dict)
• Cleanup Engine (fetches and deletes outdated events > 30 days via gcsa)
• Import Engine (pushes new events via gcsa)
c. Authentication & Configuration
• OAuth2 Credential Store (~/.credentials/credentials.json + locally cached token)
• Optional config.py / parameters (calendar_id, ics_path, open_browser)
d. External system
• Google Calendar API (REST endpoints behind gcsa client)
e. Optional utilities
• Logging / Console output
• Error handling
5. Relationships and data flows
1. User invokes main.py with ics_import() or ics_edit()
2. Script loads OAuth2 credentials → authenticates to Google
3. If ics_edit:
• Read ICS file → parse events → apply time‑zone adjustments → write back or hand off to importer
Else (ics_import):
• If no calendar_id: call Google API to create new calendar “Study”
• Query calendar for events older than 30 days → delete via API
• Read ICS file → parse events → map to API event objects (with color based on type)
• Push events to Google Calendar
4. Console logs successes/errors
6. Architectural patterns & design principles
- Single‐responsibility: separate parsing, transformation, cleanup, and import logic
- External integration point: decoupled via gcsa client
- Configuration‐driven (credentials path, calendar id, color mapping)
- No persistent local state except cached OAuth2 token
7. Diagramming guidelines tailored to this project
- Components: draw distinct boxes for
• “ICS File” (data source)
• “Authentication Module” (credentials store, OAuth flow)
• “ICS Parser” (uses ics)
• “Event Transformer” (time zones, COLORS logic)
• “Cleanup Engine”
• “Import Engine”
• “Google Calendar API” (external service)
- Show data flow with directional arrows:
• ICS File → ICS Parser → Event Transformer → Import Engine → Google API
• Authentication Module → Import Engine & Cleanup Engine → Google API
• Cleanup Engine → Google API
- Color‑code by component type:
• Green = internal modules (Parser, Transformer, Cleanup, Import)
• Blue = external systems (ICS file, Google API)
• Yellow = configuration/credentials
- Use consistent shapes: rectangles for modules, cylinders for data stores (credentials), cloud symbol for external service
- Label arrows with action verbs (e.g., “parse”, “authenticate”, “delete old events”, “create events”)
8. Additional tips
- Include callouts for the third‑party libraries (gcsa, ics, pytz) adjacent to the modules that use them
- Highlight the optional branch for calendar creation vs. using existing calendar
- Capture the cleanup loop as a sub‑process under the Cleanup Engine
- Make sure each component’s responsibilities are clearly annotated
By following this breakdown, you’ll produce a detailed, accurate UML‐style or block‐diagram that reflects every essential part of the ICS → Google Calendar import workflow, aligns with the project’s single‐tool scope, and highlights all interactions and dependencies.
</explanation>