# hdquandev/qtimetable-ictu architecture

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

- Interactive diagram: https://gitdiagram.com/hdquandev/qtimetable-ictu
- Repository: https://github.com/hdquandev/qtimetable-ictu

## Overview

##### Project type and purpose
- This is a full-stack, cross-platform mobile application built with React Native + Expo.
- Its goal is to let students view and manage their class schedules, receive real-time reminders, sync data, and share timetables. The backend is provided by Firebase (Auth + Firestore), with local persistence via AsyncStorage and background/notification handling via Expo.

##### File structure and extract main components
A. Mobile Client
- UI Layer (screens/) – all the visual pages (LoginScreen, MenuScreen, AddNoteScreen, ClassScheduleScreen, SwipeableScreens, etc.)
- Reusable Components (components/) – modal dialogs, theme provider, notification schedulers, sync utilities, log savers, update checks, Firebase config, Firestore helpers
- Navigation – React Navigation v6 configured inside App.js (and possibly a navigation/ folder)
- Context Providers – AuthContext.jsx (authentication state), ThemeProvider.jsx (theme/light-dark)
- Services/Data Layer (services/) – API wrappers (services/api.jsx), token management (services/token.jsx)
- Local Storage – AsyncStorage for caching tokens, preferences, offline data
- Background & Notification Handlers – backgroundTasks.jsx, LocalNotification.jsx, ScheduleNotification.jsx, SyncGhiChu.jsx
B. Backend / Cloud
- Firebase Authentication – user sign-up/sign-in
- Firestore Database – read/write schedule and note data
- (Optional) Firebase Cloud Messaging – if using remote push notifications
C. External & Third-Party
- React Native Calendars – calendar UI
- NativeWind/Tailwind (tailwind.config.js) – styling
D. Ops & Config
- server.py – auxiliary script or local server (maintenance or data scraping)
- CI/CD – GitHub Actions (.github/workflows/main.yml)
- Environment & Build – .env, app.json, eas.json, babel.config.js, package.json

##### Relationships and data flows
- User taps on a screen → UI Layer invokes navigation or dispatches an action
- Screen logic uses Context (AuthContext) to check auth status
- For data operations, components call services/api.jsx → API module uses firebaseConfig/firestore helpers → Firestore
- Token flows: services/token → AsyncStorage for persistence → reused on app restart
- BackgroundTasks and schedule components register tasks with Expo’s TaskManager → trigger LocalNotification or ScheduleNotification
- Cloud FCM (if enabled) sends push messages → Client receives via Expo PushNotification handlers

##### Architectural patterns and design principles
- Layered Architecture: UI Layer → Business Logic (Context & Services) → Data Layer → External Services
- Context API: centralized state for Auth and Theme
- Service Layer: abstract external calls (Firebase, AsyncStorage) behind simple methods
- Modular Components: each responsibility isolated (notification, syncing, logging, theming)
- Declarative Navigation: React Navigation for screen transitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation / UI Layer
    subgraph "Presentation / UI Layer"
        direction TB
        Screens["screens/"]:::presentation
        AppJS["App.js (Navigation)"]:::presentation
        Modal["ModalComponent.jsx"]:::presentation
        CheckUpdate["CheckUpdate.jsx"]:::presentation
    end

    %% Business Logic / Context
    subgraph "Business Logic / Context"
        direction TB
        AuthCtx["AuthContext.jsx"]:::business
        ThemeProv["ThemeProvider.jsx"]:::business
        BgTasks["backgroundTasks.jsx"]:::business
        LocalNotif["LocalNotification.jsx"]:::business
        SchedNotif["ScheduleNotification.jsx"]:::business
        SyncNotes["SyncGhiChu.jsx"]:::business
        SaveLogs["SaveLogs.jsx"]:::business
    end

    %% Data Access / Services
    subgraph "Data Access / Local Storage"
        direction TB
        API["services/api.jsx"]:::data
        TokenSvc["services/token.jsx"]:::data
        AsyncStr["AsyncStorage"]:::data
        FirebaseCfg["firebaseConfig.jsx"]:::data
        FirestoreHelpers["firestore.jsx"]:::data
    end

    %% External / Cloud / Ops
    subgraph "External Services & Ops"
        direction TB
        FirebaseAuth["Firebase Auth"]:::external
        FirestoreDB["Firestore Database"]:::external
        FCM["Firebase Cloud Messaging"]:::external
        ExpoPush["Expo Notifications"]:::external
        RNCalendars["React Native Calendars"]:::external
        Tailwind["tailwind.config.js"]:::external
        ServerScript["server.py"]:::external
        CICD[".github/workflows/main.yml"]:::external
        EnvVars[".env"]:::external
        AppJSON["app.json"]:::external
        EAS["eas.json"]:::external
        BabelCfg["babel.config.js"]:::external
        PackageJSON["package.json"]:::external
    end

    %% Relationships
    Screens -->|uses| AuthCtx
    Screens -->|uses| ThemeProv
    Screens -->|dispatch actions| API
    AuthCtx -->|calls| API
    ThemeProv -->|provides theme| Screens

    API -->|configs| FirebaseCfg
    API -->|uses| FirestoreHelpers
    TokenSvc -->|stores tokens| AsyncStr
    API -->|reads/writes tokens| TokenSvc
    FirestoreHelpers -->|connects to| FirestoreDB
    FirebaseCfg -->|auth config| FirebaseAuth

    BgTasks -->|schedules| LocalNotif
    BgTasks -->|schedules| SchedNotif
    SyncNotes -->|syncs| FirestoreDB
    LocalNotif -->|push via| ExpoPush
    SchedNotif -->|push via| ExpoPush

    FCM -->|push messages| ExpoPush
    ExpoPush -->|notifies| LocalNotif

    %% Click Events
    click Screens "https://github.com/hdquandev/qtimetable-ictu/tree/master/screens/"
    click AppJS "https://github.com/hdquandev/qtimetable-ictu/blob/master/App.js"
    click AuthCtx "https://github.com/hdquandev/qtimetable-ictu/blob/master/AuthContext.jsx"
    click ThemeProv "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/ThemeProvider.jsx"
    click Modal "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/ModalComponent.jsx"
    click CheckUpdate "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/CheckUpdate.jsx"
    click LocalNotif "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/LocalNotification.jsx"
    click SchedNotif "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/ScheduleNotification.jsx"
    click BgTasks "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/backgroundTasks.jsx"
    click SyncNotes "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/SyncGhiChu.jsx"
    click SaveLogs "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/SaveLogs.jsx"
    click FirebaseCfg "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/firebaseConfig.jsx"
    click FirestoreHelpers "https://github.com/hdquandev/qtimetable-ictu/blob/master/components/firestore.jsx"
    click API "https://github.com/hdquandev/qtimetable-ictu/blob/master/services/api.jsx"
    click TokenSvc "https://github.com/hdquandev/qtimetable-ictu/blob/master/services/token.jsx"
    click ServerScript "https://github.com/hdquandev/qtimetable-ictu/blob/master/server.py"
    click CICD "https://github.com/hdquandev/qtimetable-ictu/blob/master/.github/workflows/main.yml"
    click EnvVars "https://github.com/hdquandev/qtimetable-ictu/blob/master/.env"
    click AppJSON "https://github.com/hdquandev/qtimetable-ictu/blob/master/app.json"
    click EAS "https://github.com/hdquandev/qtimetable-ictu/blob/master/eas.json"
    click BabelCfg "https://github.com/hdquandev/qtimetable-ictu/blob/master/babel.config.js"
    click PackageJSON "https://github.com/hdquandev/qtimetable-ictu/blob/master/package.json"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef business fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
