# supermuel/syncademic architecture

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

- Interactive diagram: https://gitdiagram.com/supermuel/syncademic
- Repository: https://github.com/supermuel/syncademic

## Overview

##### Project Type and Purpose
- The project is a full-stack application with a clear separation between the backend/cloud functions and the frontend mobile/web app.

##### File Structure
- There are three main directories representing distinct system components:
- “functions”: Contains the backend logic implemented as Firebase Cloud Functions. This includes services (for AI rulesets, authorization, ICS handling, synchronization, etc.), repositories, models, and tests. It orchestrates database interactions (Firestore) and external APIs (Google Calendar API).
- “syncademic_app”: Contains the Flutter-based frontend code that supports mobile, web, and Android apps. This module handles user interactions, authentication flows, calendar sync presentation, and UI screens.
- “admin”: Likely serves as an administrative interface or dashboard with its own Python backend components that manage internal logic and pages.
- Additionally, configuration files like firebase.json, firestore.* files, Dockerfiles, CI/CD files (located in the .github/workflows folder) and environment configurations indicate standard deployment and development practices.

##### Key Architectural Components to Highlight
a. Frontend (Client Side)
- The Flutter application (“syncademic_app”) that runs on multiple platforms (mobile/web). It provides UI and manages user authentication, synchronization setup, and calendar visualization.
b. Backend Services
- Firebase Cloud Functions (“functions”): Handles the core business logic – authenticating users, processing ICS URLs, managing sync profiles, interfacing with Google Calendar API, and integrating AI tools.
- Firebase Firestore: Serves as the database for storing user profiles, sync configurations, and logs.
c. Admin Interface
- The “admin” module provides an administrative dashboard for managing system aspects such as configurations, potentially monitoring synchronization events, or handling error tracking.
d. External and AI Components
- Google Calendar API: For calendar update operations triggered by backend functions.
- AI and Customization Services: Integration with GPT-4 (gpt-4o) and Langchain for generating and applying customization rules. The clustering mechanism (using TF-IDF and HDBSCAN) for schedule events should be depicted.
- Firebase Auth: For authentication across the system.
- Firebase Hosting: Used for hosting the frontend web app.

##### Relationships and Data Flows
- The Flutter frontend communicates with the Firebase backend (via REST or function calls) to authenticate users, set up sync profiles, and trigger calendar synchronization.
- Firebase Cloud Functions perform the heavy lifting:
- They validate ICS URLs and process the schedule data.
- They use AI services to parse input, cluster events, and generate customization rules.
- They update the Google Calendar through the Calendar API.
- They interact with Firestore to store and retrieve user profiles and sync configurations.
- The admin module can be seen as an independent interface (or as part of internal tools) that accesses backend APIs and database information for management and monitoring.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinct modules for frontend (Flutter), backend (Firebase Functions & Firestore), and admin services.
- Microservices-like approach within the “functions” directory, where functionalities are split into clear logical units (models, repositories, services, synchronizer).
- Testability: The presence of detailed tests across models, services, and synchronizers suggests a design that encourages unit testing and modular code.
- CI/CD Integration: Workflows configured in GitHub Actions facilitate automated testing and deployment to Firebase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client Frontend"
        FE["Flutter App (UI & Calendar)"]:::frontend
        FE_AUTH["Authentication Module (Client)"]:::frontend
    end

    %% Backend Cloud Functions
    subgraph "Backend Cloud Functions"
        B_FUNC["Firebase Functions (Core Logic)"]:::backend
        B_AUTH_MODEL["Authorization Model"]:::backend
        B_AUTH_SERVICE["Authorization Service"]:::backend
        ICS["ICS Processing & Schedule Sync"]:::backend
        AI["AI & Customization Services"]:::backend
        MODELS["Data Models"]:::backend
        REPOS["Repositories"]:::backend
        DB["Firestore\n(Database)"]:::backend
    end

    %% Admin Interface
    subgraph "Admin Panel"
        ADMIN["Admin Dashboard"]:::admin
    end

    %% External Services
    subgraph "External Services"
        GC["Google Calendar API"]:::external
        FH["Firebase Hosting"]:::external
    end

    %% CI/CD & Configurations
    subgraph "CI/CD & Configurations"
        CICD["CI/CD Workflows"]:::cicd
        CONFIG1["firebase.json"]:::cicd
        CONFIG2["firestore.rules"]:::cicd
        CONFIG3["firestore.indexes.json"]:::cicd
    end

    %% Connections between Components
    FE -->|"authenticate_sync"| B_FUNC
    FE_AUTH -->|"send_auth_data"| B_AUTH_SERVICE
    B_FUNC -->|"validate_auth"| B_AUTH_SERVICE
    B_AUTH_MODEL -->|"provides_rules"| B_AUTH_SERVICE
    B_FUNC -->|"process_ICS"| ICS
    B_FUNC -->|"invoke_AI"| AI
    B_FUNC -->|"utilizes"| MODELS
    B_FUNC -->|"utilizes"| REPOS
    B_FUNC -->|"stores_data"| DB
    ICS -->|"syncs_with"| GC
    ADMIN -->|"manages"| B_FUNC
    ADMIN -->|"monitors"| DB
    CICD -->|"deploys_to"| B_FUNC
    CICD -->|"deploys_to"| FE
    CICD -->|"configures"| CONFIG1
    CICD -->|"configures"| CONFIG2
    CICD -->|"configures"| CONFIG3

    %% Click Events (Component Mappings)
    click FE "https://github.com/supermuel/syncademic/tree/main/syncademic_app"
    click FE_AUTH "https://github.com/supermuel/syncademic/tree/main/syncademic_app/lib/authorization"
    click B_FUNC "https://github.com/supermuel/syncademic/tree/main/functions"
    click AI "https://github.com/supermuel/syncademic/tree/main/functions/functions/ai"
    click MODELS "https://github.com/supermuel/syncademic/tree/main/functions/functions/models"
    click REPOS "https://github.com/supermuel/syncademic/tree/main/functions/functions/repositories"
    click B_AUTH_MODEL "https://github.com/supermuel/syncademic/blob/main/functions/functions/models/authorization.py"
    click B_AUTH_SERVICE "https://github.com/supermuel/syncademic/blob/main/functions/functions/services/authorization_service.py"
    click ADMIN "https://github.com/supermuel/syncademic/tree/main/admin"
    click CICD "https://github.com/supermuel/syncademic/tree/main/.github/workflows"
    click CONFIG1 "https://github.com/supermuel/syncademic/blob/main/firebase.json"
    click CONFIG2 "https://github.com/supermuel/syncademic/blob/main/firestore.rules"
    click CONFIG3 "https://github.com/supermuel/syncademic/blob/main/firestore.indexes.json"

    %% Style Definitions
    classDef frontend fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef backend fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef admin fill:#D5F5E3,stroke:#000,stroke-width:1px;
    classDef external fill:#F5CBA7,stroke:#000,stroke-width:1px;
    classDef cicd fill:#DFE3E6,stroke:#000,stroke-width:1px;
```
