# hayden9898/syllascan architecture

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

- Interactive diagram: https://gitdiagram.com/hayden9898/syllascan
- Repository: https://github.com/hayden9898/syllascan

## Overview

##### Project Type and Purpose
- SyllaScan is a full-stack web application.
- Frontend: a React.js SPA styled with Tailwind CSS.
- Backend: a Python service (likely FastAPI/Flask based on structure) that handles syllabus processing, AI calls, and calendar integration.
- Purpose: upload syllabus → extract dates via OpenAI → integrate with Google Calendar.

##### File Structure
- Top-level:
- app/ – backend source (helpers, routers, main.py)
- frontend/ – React app (public, src, Tailwind config)
- backend “helpers” correspond to service adapters: OpenAI, Google OAuth, Google Calendar.
- routers define HTTP endpoints: upload/scan syllabus, OAuth flow, calendar sync.
- frontend/src contains pages (Home, Login, DrivePicker, ExportPage, Results) and shared components (Button, Loader).

##### README for Stack & Workflow
- Tech: React.js, OpenAI, Google Calendar API, Tailwind CSS.
- Flow: user authenticates with Google → uploads syllabus → backend uses OpenAI to parse dates → backend writes events via Google Calendar API → frontend displays results and status.

a. Main Components:
- Client Browser (React SPA)
- Frontend Application
- Backend Service (app/main.py)
- External AI Service (OpenAI API)
- External Calendar Service (Google Calendar API)
- (Optional) Local Storage (dummy_json.json or future DB)

b. Interactions:
1. User → Frontend: navigation, file upload
2. Frontend → Backend: REST/HTTP POST (upload syllabus)
3. Backend → OpenAI API: send document, receive parsed dates
4. Backend → Google OAuth API: authenticate & obtain tokens
5. Backend → Google Calendar API: create/update events
6. Backend → Frontend: send sync status & event list
7. Frontend → Browser: render calendar results, allow export

c. Architectural Patterns / Principles:
- SPA + REST API separation
- Adapter pattern for external service integrations (helpers/)
- Router-based endpoint organization
- Stateless backend (no persistent DB shown)

d. Key Technologies:
- Frontend: React.js, Tailwind CSS, IndexedDB (for any client-side caching), Drive Picker components
- Backend: Python (FastAPI/Flask style), pip dependencies, JSON stub data
- External: OpenAI API, Google Calendar API (with OAuth2 flow)

- Blue for frontend components
- Green for backend components
- Orange for external services
- Rectangles for services/applications
- Clouds for external APIs

Final Advice
- Be exhaustive: include each module group (routers, helpers, components).
- Data flow: from file upload → AI parsing → calendar creation → UI feedback.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Client Browser"
    Browser("Web Browser"):::external
  end

  subgraph "Frontend Layer"
    direction TB
    FrontendApp("React SPA"):::frontend
    HomePage("Home Page"):::frontend
    DrivePicker("Drive Picker Page"):::frontend
    ExportPage("Export Page"):::frontend
    ResultsPage("Results Page"):::frontend
    LoginComp("Login Component"):::frontend
    subgraph "Shared UI Components"
      direction TB
      Button("Button"):::frontend
      Loader("Loader"):::frontend
      Label("Label"):::frontend
      PersistState("PersistentState Hook"):::frontend
    end
    IndexedDB("IndexedDB Cache"):::frontend
  end

  subgraph "Backend Layer"
    direction TB
    BackendAPI("Backend API Service"):::backend
    subgraph "Routers"
      GoogleOps("Google Calendar Router"):::backend
      OAuthRouter("OAuth Router"):::backend
    end
    subgraph "Helpers (Adapters)"
      OpenAIAdapter("OpenAI Adapter"):::backend
      GoogleCreds("Google Credentials Adapter"):::backend
      GCalAdapter("Google Calendar Adapter"):::backend
      CalendarAbst("Calendar Data Abstraction"):::backend
    end
    DummyJSON(["dummy_json.json"]):::db
  end

  subgraph "External Services"
    direction TB
    OpenAIAPI("OpenAI API"):::external
    GoogleOAuthAPI("Google OAuth API"):::external
    GoogleCalAPI("Google Calendar API"):::external
  end

  Browser --> FrontendApp
  FrontendApp --> HomePage
  FrontendApp --> DrivePicker
  FrontendApp --> ExportPage
  FrontendApp --> ResultsPage
  FrontendApp --> LoginComp
  FrontendApp --> Button
  FrontendApp --> Loader
  FrontendApp --> Label
  FrontendApp --> PersistState
  FrontendApp --> IndexedDB

  FrontendApp -->|"POST /scan, /oauth, /calendar"| BackendAPI
  BackendAPI --> GoogleOps
  BackendAPI --> OAuthRouter
  BackendAPI --> OpenAIAdapter
  BackendAPI --> GoogleCreds
  BackendAPI --> GCalAdapter
  BackendAPI --> CalendarAbst
  BackendAPI --> DummyJSON

  OpenAIAdapter -->|"API Calls"| OpenAIAPI
  GoogleCreds -->|"OAuth Flow"| GoogleOAuthAPI
  GCalAdapter -->|"Event Operations"| GoogleCalAPI

  OpenAIAPI --> OpenAIAdapter
  GoogleOAuthAPI --> GoogleCreds
  GoogleCalAPI --> GCalAdapter

  BackendAPI -->|"200 OK, events list"| FrontendApp
  FrontendApp --> Browser

  click FrontendApp "https://github.com/hayden9898/syllascan/blob/main/frontend/src/App.js"
  click HomePage "https://github.com/hayden9898/syllascan/blob/main/frontend/src/Home/page.js"
  click DrivePicker "https://github.com/hayden9898/syllascan/blob/main/frontend/src/DrivePicker/page.js"
  click ExportPage "https://github.com/hayden9898/syllascan/blob/main/frontend/src/ExportPage/page.js"
  click ResultsPage "https://github.com/hayden9898/syllascan/blob/main/frontend/src/Results/page.js"
  click LoginComp "https://github.com/hayden9898/syllascan/blob/main/frontend/src/Login/Google.jsx"
  click Button "https://github.com/hayden9898/syllascan/blob/main/frontend/src/components/Button.js"
  click Loader "https://github.com/hayden9898/syllascan/blob/main/frontend/src/components/Loader.js"
  click Label "https://github.com/hayden9898/syllascan/blob/main/frontend/src/components/Label.js"
  click PersistState "https://github.com/hayden9898/syllascan/blob/main/frontend/src/components/PersistentState.js"
  click IndexedDB "https://github.com/hayden9898/syllascan/blob/main/frontend/src/indexedDb.js"
  click BackendAPI "https://github.com/hayden9898/syllascan/blob/main/app/main.py"
  click GoogleOps "https://github.com/hayden9898/syllascan/blob/main/app/routers/google.py"
  click OAuthRouter "https://github.com/hayden9898/syllascan/blob/main/app/routers/google_oauth.py"
  click OpenAIAdapter "https://github.com/hayden9898/syllascan/blob/main/app/helpers/openai.py"
  click GoogleCreds "https://github.com/hayden9898/syllascan/blob/main/app/helpers/google_credentials.py"
  click GCalAdapter "https://github.com/hayden9898/syllascan/blob/main/app/helpers/gcal.py"
  click CalendarAbst "https://github.com/hayden9898/syllascan/blob/main/app/helpers/calendar.py"
  click DummyJSON "https://github.com/hayden9898/syllascan/blob/main/app/dummy_json.json"

  classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
  classDef external fill:#F4A460,stroke:#333,stroke-width:1px
  classDef db fill:#FFE4B5,stroke:#333,stroke-width:1px
```
