# polito/students-app architecture

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

- Interactive diagram: https://gitdiagram.com/polito/students-app
- Repository: https://github.com/polito/students-app

## Overview

##### Project Type and Purpose
- This is a React Native mobile application (“PoliTO Students App”) targeting iOS and Android platforms.
- It provides students of Politecnico di Torino with features such as agenda, courses, bookings, maps, notifications, messaging and more by calling Polito’s public/internal APIs.

##### High-Level Architecture Overview
- The system is purely a mobile client (no in-repo backend) that bundles JavaScript/TypeScript code via Metro and interacts at runtime with:
- Native modules (iOS/Android code for push notifications, file system, keychain, etc.)
- External services (Polito RESTful APIs, Firebase, Sentry, asset servers)
- Local storage (AsyncStorage, file system caches)

##### Main Components
A. Presentation Layer (React Native JS)
- `src` – Application entry point (`App.tsx`), navigation containers, screens, feature modules.
- `lib/ui` – Shared UI component library (buttons, cards, calendar, bottom sheets, etc.).
- Feature subfolders (`src/features/*`) – Agenda, Courses, Bookings, Places, Services, etc., each with its own components, hooks, contexts, queries and navigation.
B. State & Business Logic
- Context Providers (ApiProvider, PreferencesProvider, DownloadsProvider, etc.)
- Hooks & React-Query-style queries (in `src/core/hooks` & `src/core/queries`)
- Migrations & caching services (MigrationService, CourseFilesCacheProvider)
C. Data Layer
- API layer (`src/config/api.tsx`, ApiContext): HTTP client configuration, base URLs, auth token injection.
- Local persistence: AsyncStorage or file-system for downloaded course files. Keychain for secrets.
D. Native Bridge Layer
- iOS (Objective-C/Swift) & Android (Kotlin/Java) projects under `ios/` and `android/` – push notifications (Firebase), asset linking, custom native modules.
- React Native bridge (`react-native.config.js`) connecting JS → Native.
E. External Services
- Polito backend APIs (authentication, data endpoints)
- Firebase (push notifications, remote config if used)
- Sentry (error reporting)

##### Interactions & Data Flows
- On app start: JS bundle loads, `App.tsx` initializes providers → ApiProvider fetches config → NavigationContainer mounts.
- User action in UI → Screen component dispatches query hook → ApiContext issues HTTP request → Polito API responds → Data cached in context or local storage → UI re-renders.
- Background downloads (course files) use native file-system module via bridge.
- Push notifications received by native code → forwarded to JS via bridge → Notification hooks update UI.
- Errors caught in JS or native → sent to Sentry.

##### Architectural Patterns & Principles
- Feature-based modularization: each feature folder encapsulates its UI, data-fetching, state, and navigation.
- Unidirectional data flow: components → hooks/contexts → API/storage → back to components.
- Separation of concerns: `lib/ui` for generic UI, `src/core` for cross-cutting logic, `src/features` for domain functionality.
- Provider pattern: React Contexts wrap the app to supply dependencies.

##### Technologies & Frameworks to Annotate
- React Native + TypeScript
- Metro bundler
- React Navigation
- React Context & Hooks
- Babel, ESLint, Prettier, Husky (pre-commit)
- Fastlane (iOS/Android CI)
- Gradle (Android), CocoaPods (iOS)
- Firebase SDK, Sentry SDK

##### Final Advice
- React Native bridge – that is the heart of integration between JS and native subsystems.
- Core architectural elements: Presentation → Business Logic → Data → Native Bridge → External Services.
- Do not overload with every single file; group by folder and functionality. This balance yields clarity and accuracy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        App["App.tsx"]:::js
        NavContainer["NavigationContainer"]:::js
        RootNav["RootNavigator"]:::js
        UI["Shared UI Library (lib/ui)"]:::js
        subgraph "Features"
            direction TB
            Agenda["Agenda"]:::js
            Courses["Courses"]:::js
            Bookings["Bookings"]:::js
            Places["Places"]:::js
            Services["Services"]:::js
        end
    end

    %% Business & State Layer
    subgraph "Business & State Layer"
        direction TB
        subgraph "Context Providers"
            ApiProvider["ApiProvider"]:::js
            PreferencesProvider["PreferencesProvider"]:::js
            DownloadsProvider["DownloadsProvider"]:::js
            FeedbackProvider["FeedbackProvider"]:::js
            SplashProvider["SplashProvider"]:::js
            UiProvider["UiProvider"]:::js
        end
        subgraph "Hooks"
            HooksDir["Hooks Directory"]:::js
            useProcessedLectures["useProcessedLectures"]:::js
            useCalculateSeatsDimension["useCalculateSeatsDimension"]:::js
        end
        subgraph "Queries"
            QueriesDir["Queries Directory"]:::js
            agendaHooks["agendaHooks"]:::js
            lectureHooks["lectureHooks"]:::js
        end
        subgraph "Migrations & Caching"
            MigrationService["MigrationService"]:::js
            MigrationsDir["Migrations Directory"]:::js
            CourseCache["CourseFilesCacheProvider"]:::js
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        APIConfig["api.tsx"]:::js
        ApiContextNode["ApiContext"]:::js
        FilesUtil["files.ts"]:::storage
        KeychainUtil["keychain.ts"]:::storage
        AsyncStorage["AsyncStorage"]:::storage
    end

    %% Native Bridge Layer
    subgraph "Native Bridge Layer"
        direction TB
        IOS["iOS Project"]:::native
        Android["Android Project"]:::native
        RNConfig["react-native.config.js"]:::js
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PolitoAPI["Polito REST APIs"]:::external
        Firebase["Firebase"]:::external
        Sentry["Sentry"]:::external
        CDN["CDN / Asset Host"]:::external
    end

    %% Connections
    ApiProvider -->|wraps| App
    PreferencesProvider --> App
    DownloadsProvider --> App
    FeedbackProvider --> App
    SplashProvider --> App
    UiProvider --> App

    App --> NavContainer
    NavContainer --> RootNav
    RootNav --> Agenda
    RootNav --> Courses
    RootNav --> Bookings
    RootNav --> Places
    RootNav --> Services
    App --> UI

    Agenda -->|uses| HooksDir
    Courses -->|uses| HooksDir
    Bookings -->|uses| HooksDir
    Places -->|uses| HooksDir
    Services -->|uses| HooksDir

    HooksDir --> useProcessedLectures
    HooksDir --> useCalculateSeatsDimension

    Agenda -->|fetch| agendaHooks
    Agenda -->|fetch| lectureHooks
    agendaHooks --> APIConfig
    lectureHooks --> APIConfig

    HooksDir --> APIConfig
    ApiProvider --> APIConfig
    APIConfig --> PolitoAPI
    ApiContextNode --> APIConfig

    CourseCache --> FilesUtil
    CourseCache --> AsyncStorage
    CourseCache --> KeychainUtil

    FilesUtil --> IOS
    FilesUtil --> Android
    RNConfig --> IOS
    RNConfig --> Android

    IOS -->|push notifications| Firebase
    Android -->|push notifications| Firebase
    IOS -->|error reports| Sentry
    Android -->|error reports| Sentry
    App -->|error reports| Sentry

    APIConfig -.->|static assets| CDN

    %% Click Events
    click App "https://github.com/polito/students-app/blob/main/src/App.tsx"
    click NavContainer "https://github.com/polito/students-app/blob/main/src/core/components/NavigationContainer.tsx"
    click RootNav "https://github.com/polito/students-app/blob/main/src/core/components/RootNavigator.tsx"
    click UI "https://github.com/polito/students-app/tree/main/lib/ui"
    click Agenda "https://github.com/polito/students-app/tree/main/src/features/agenda"
    click Courses "https://github.com/polito/students-app/tree/main/src/features/courses"
    click Bookings "https://github.com/polito/students-app/tree/main/src/features/bookings"
    click Places "https://github.com/polito/students-app/tree/main/src/features/places"
    click Services "https://github.com/polito/students-app/tree/main/src/features/services"
    click ApiProvider "https://github.com/polito/students-app/blob/main/src/core/providers/ApiProvider.tsx"
    click PreferencesProvider "https://github.com/polito/students-app/blob/main/src/core/providers/PreferencesProvider.tsx"
    click DownloadsProvider "https://github.com/polito/students-app/blob/main/src/core/providers/DownloadsProvider.tsx"
    click FeedbackProvider "https://github.com/polito/students-app/blob/main/src/core/providers/FeedbackProvider.tsx"
    click SplashProvider "https://github.com/polito/students-app/blob/main/src/core/providers/SplashProvider.tsx"
    click UiProvider "https://github.com/polito/students-app/blob/main/src/core/providers/UiProvider.tsx"
    click HooksDir "https://github.com/polito/students-app/tree/main/src/core/hooks"
    click useProcessedLectures "https://github.com/polito/students-app/blob/main/src/features/agenda/hooks/useProcessedLectures.ts"
    click useCalculateSeatsDimension "https://github.com/polito/students-app/blob/main/src/features/bookings/hooks/useCalculateSeatsDimension.ts"
    click QueriesDir "https://github.com/polito/students-app/tree/main/src/core/queries"
    click agendaHooks "https://github.com/polito/students-app/blob/main/src/features/agenda/queries/agendaHooks.ts"
    click lectureHooks "https://github.com/polito/students-app/blob/main/src/features/agenda/queries/lectureHooks.ts"
    click MigrationService "https://github.com/polito/students-app/blob/main/src/core/migrations/MigrationService.ts"
    click MigrationsDir "https://github.com/polito/students-app/tree/main/src/core/migrations"
    click CourseCache "https://github.com/polito/students-app/blob/main/src/features/courses/providers/CourseFilesCacheProvider.tsx"
    click APIConfig "https://github.com/polito/students-app/blob/main/src/config/api.tsx"
    click ApiContextNode "https://github.com/polito/students-app/blob/main/src/core/contexts/ApiContext.ts"
    click FilesUtil "https://github.com/polito/students-app/blob/main/src/utils/files.ts"
    click KeychainUtil "https://github.com/polito/students-app/blob/main/src/utils/keychain.ts"
    click IOS "https://github.com/polito/students-app/tree/main/ios/"
    click Android "https://github.com/polito/students-app/tree/main/android/"
    click RNConfig "https://github.com/polito/students-app/blob/main/react-native.config.js"
    click Firebase "https://github.com/polito/students-app/blob/main/firebase.json"
    click Sentry "https://github.com/polito/students-app/blob/main/ .sentryclirc"

    %% Styles
    classDef js fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef native fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef storage fill:#D0F2D0,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#FFCDD2,stroke:#B71C1C,color:#B71C1C;
```
