# papillonapp/papillon architecture

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

- Interactive diagram: https://gitdiagram.com/papillonapp/papillon
- Repository: https://github.com/papillonapp/papillon
- Video tour (about a minute): https://gitdiagram.com/papillonapp/papillon/video

## Overview

Papillon is a mobile school-life app for viewing and managing school information across several education-service providers, with local account and school-data storage. The user-facing flow starts with onboarding and account setup, then screens request school data through a shared service manager and display it in areas such as the home, timetable, grades, and tasks. The graph also retains news, attendance, messaging, canteen, and local calendar capabilities visible in the repository. Some links are documented only by the source index; unsampled wiring is not inferred.

Main entry points: [`services/shared/index.ts`](https://github.com/papillonapp/papillon/blob/dev/services/shared/index.ts) (Service manager), [`database/useHomework.ts`](https://github.com/papillonapp/papillon/blob/dev/database/useHomework.ts) (Homework storage), [`services/shared`](https://github.com/papillonapp/papillon/tree/dev/services/shared) (Shared service data), [`app/(tabs)/index/hooks/useHomeData.ts`](https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/index/hooks/useHomeData.ts) (Home data hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Onboarding and accounts"]
  node_onboarding["Onboarding flow"]
  node_account["Account state<br/>[index.ts]"]
end

subgraph group_service["School service integration"]
  node_manager["Service manager<br/>[index.ts]"]
  node_contracts["Shared service data"]
  node_pronote["Pronote adapter<br/>[index.ts]"]
  node_ecoledirecte["EcoleDirecte adapter<br/>[index.ts]"]
  node_skolengo["Skolengo adapter<br/>[index.ts]"]
  node_other_services["Other provider adapters"]
end

subgraph group_data["Local data"]
  node_db_provider[("Database provider")]
  node_homework_store["Homework storage<br/>[useHomework.ts]"]
  node_db_transactions["Safe transactions<br/>[safeTransaction.ts]"]
  node_database_models["School-data models"]
end

subgraph group_product["School life features"]
  node_home["Home dashboard"]
  node_home_data["Home data hook<br/>[useHomeData.ts]"]
  node_calendar["Calendar and timetable"]
  node_grades["Grades"]
  node_grades_data["Grades data hook<br/>[useGradesData.ts]"]
  node_tasks["Tasks and homework"]
  node_tasks_data["Homework data hook<br/>[useHomeworkData.ts]"]
  node_news["News"]
  node_attendance["Attendance<br/>[attendance.tsx]"]
  node_cards["School cards"]
  node_ical["Local calendar imports<br/>[ical.ts]"]
end

node_user(("Student or family"))
node_school_services(("School platforms"))

node_user -->|"starts setup"| node_onboarding
node_onboarding -.->|"configures accounts"| node_account
node_home -.->|"loads dashboard"| node_home_data
node_home_data -->|"requests school data"| node_manager
node_home_data -->|"reads homework"| node_homework_store
node_grades -.->|"loads grades"| node_grades_data
node_grades_data -->|"requests grades"| node_manager
node_tasks -.->|"loads homework"| node_tasks_data
node_tasks_data -->|"requests homework"| node_manager
node_tasks_data -->|"reads and writes"| node_homework_store
node_manager -->|"caches results"| node_homework_store
node_homework_store -->|"opens database"| node_db_provider
node_homework_store -->|"writes safely"| node_db_transactions
node_db_provider -->|"registers models"| node_database_models
node_manager -->|"uses shared types"| node_contracts
node_pronote -->|"implements contracts"| node_contracts
node_ecoledirecte -->|"implements contracts"| node_contracts
node_skolengo -->|"implements contracts"| node_contracts
node_manager -.->|"dispatches requests"| node_pronote
node_manager -.->|"dispatches requests"| node_ecoledirecte
node_manager -.->|"dispatches requests"| node_skolengo
node_manager -.->|"supports providers"| node_other_services
node_school_services -.->|"serves data"| node_pronote
node_school_services -.->|"serves data"| node_ecoledirecte
node_school_services -.->|"serves data"| node_skolengo
node_calendar -.->|"imports calendars"| node_ical
node_manager -.->|"provides timetable"| node_calendar
node_manager -.->|"provides news"| node_news
node_manager -.->|"provides attendance"| node_attendance
node_manager -.->|"provides grades"| node_grades
node_manager -.->|"provides balances"| node_cards

click node_onboarding "https://github.com/papillonapp/papillon/tree/dev/app/(onboarding)"
click node_account "https://github.com/papillonapp/papillon/blob/dev/stores/account/index.ts"
click node_manager "https://github.com/papillonapp/papillon/blob/dev/services/shared/index.ts"
click node_contracts "https://github.com/papillonapp/papillon/tree/dev/services/shared"
click node_pronote "https://github.com/papillonapp/papillon/blob/dev/services/pronote/index.ts"
click node_ecoledirecte "https://github.com/papillonapp/papillon/blob/dev/services/ecoledirecte/index.ts"
click node_skolengo "https://github.com/papillonapp/papillon/blob/dev/services/skolengo/index.ts"
click node_other_services "https://github.com/papillonapp/papillon/tree/dev/services"
click node_db_provider "https://github.com/papillonapp/papillon/blob/dev/database/DatabaseProvider.tsx"
click node_homework_store "https://github.com/papillonapp/papillon/blob/dev/database/useHomework.ts"
click node_db_transactions "https://github.com/papillonapp/papillon/blob/dev/database/utils/safeTransaction.ts"
click node_home "https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/index"
click node_home_data "https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/index/hooks/useHomeData.ts"
click node_calendar "https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/calendar"
click node_grades "https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/grades"
click node_grades_data "https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/grades/hooks/useGradesData.ts"
click node_tasks "https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/tasks"
click node_tasks_data "https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/tasks/hooks/useHomeworkData.ts"
click node_news "https://github.com/papillonapp/papillon/tree/dev/app/(features)/(news)"
click node_attendance "https://github.com/papillonapp/papillon/blob/dev/app/(features)/attendance.tsx"
click node_cards "https://github.com/papillonapp/papillon/tree/dev/app/(features)/(cards)"
click node_database_models "https://github.com/papillonapp/papillon/tree/dev/database/models"
click node_ical "https://github.com/papillonapp/papillon/blob/dev/services/local/ical.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_onboarding,node_account toneBlue
class node_manager,node_contracts,node_pronote,node_ecoledirecte,node_skolengo,node_other_services toneAmber
class node_db_provider,node_homework_store,node_db_transactions,node_database_models toneMint
class node_home,node_home_data,node_calendar,node_grades,node_grades_data,node_tasks,node_tasks_data,node_news,node_attendance,node_cards,node_ical toneRose
class node_user,node_school_services toneIndigo
```

## Components

### Onboarding and accounts

- [Onboarding flow](https://github.com/papillonapp/papillon/tree/dev/app/(onboarding)): `app/(onboarding)`
- [Account state](https://github.com/papillonapp/papillon/blob/dev/stores/account/index.ts): `stores/account/index.ts`

### School service integration

- [Service manager](https://github.com/papillonapp/papillon/blob/dev/services/shared/index.ts): `services/shared/index.ts`
- [Shared service data](https://github.com/papillonapp/papillon/tree/dev/services/shared): `services/shared`
- [Pronote adapter](https://github.com/papillonapp/papillon/blob/dev/services/pronote/index.ts): `services/pronote/index.ts`
- [EcoleDirecte adapter](https://github.com/papillonapp/papillon/blob/dev/services/ecoledirecte/index.ts): `services/ecoledirecte/index.ts`
- [Skolengo adapter](https://github.com/papillonapp/papillon/blob/dev/services/skolengo/index.ts): `services/skolengo/index.ts`
- [Other provider adapters](https://github.com/papillonapp/papillon/tree/dev/services): `services`

### Local data

- [Database provider](https://github.com/papillonapp/papillon/blob/dev/database/DatabaseProvider.tsx): `database/DatabaseProvider.tsx`
- [Homework storage](https://github.com/papillonapp/papillon/blob/dev/database/useHomework.ts): `database/useHomework.ts`
- [Safe transactions](https://github.com/papillonapp/papillon/blob/dev/database/utils/safeTransaction.ts): `database/utils/safeTransaction.ts`
- [School-data models](https://github.com/papillonapp/papillon/tree/dev/database/models): `database/models`

### School life features

- [Home dashboard](https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/index): `app/(tabs)/index`
- [Home data hook](https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/index/hooks/useHomeData.ts): `app/(tabs)/index/hooks/useHomeData.ts`
- [Calendar and timetable](https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/calendar): `app/(tabs)/calendar`
- [Grades](https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/grades): `app/(tabs)/grades`
- [Grades data hook](https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/grades/hooks/useGradesData.ts): `app/(tabs)/grades/hooks/useGradesData.ts`
- [Tasks and homework](https://github.com/papillonapp/papillon/tree/dev/app/(tabs)/tasks): `app/(tabs)/tasks`
- [Homework data hook](https://github.com/papillonapp/papillon/blob/dev/app/(tabs)/tasks/hooks/useHomeworkData.ts): `app/(tabs)/tasks/hooks/useHomeworkData.ts`
- [News](https://github.com/papillonapp/papillon/tree/dev/app/(features)/(news)): `app/(features)/(news)`
- [Attendance](https://github.com/papillonapp/papillon/blob/dev/app/(features)/attendance.tsx): `app/(features)/attendance.tsx`
- [School cards](https://github.com/papillonapp/papillon/tree/dev/app/(features)/(cards)): `app/(features)/(cards)`
- [Local calendar imports](https://github.com/papillonapp/papillon/blob/dev/services/local/ical.ts): `services/local/ical.ts`

### Other components

- **Student or family**
- **School platforms**

## Connections

- Student or family → Onboarding flow: starts setup (evidence: `README.md`)
- Onboarding flow → Account state: configures accounts
- Home dashboard → Home data hook: loads dashboard
- Home data hook → Service manager: requests school data (evidence: `app/(tabs)/index/hooks/useHomeData.ts`)
- Home data hook → Homework storage: reads homework (evidence: `app/(tabs)/index/hooks/useHomeData.ts`)
- Grades → Grades data hook: loads grades
- Grades data hook → Service manager: requests grades (evidence: `app/(tabs)/grades/hooks/useGradesData.ts`)
- Tasks and homework → Homework data hook: loads homework
- Homework data hook → Service manager: requests homework (evidence: `app/(tabs)/tasks/hooks/useHomeworkData.ts`)
- Homework data hook → Homework storage: reads and writes (evidence: `app/(tabs)/tasks/hooks/useHomeworkData.ts`)
- Service manager → Homework storage: caches results (evidence: `services/shared/index.ts`)
- Homework storage → Database provider: opens database (evidence: `database/useHomework.ts`)
- Homework storage → Safe transactions: writes safely (evidence: `database/useHomework.ts`)
- Database provider → School-data models: registers models (evidence: `database/DatabaseProvider.tsx`)
- Service manager → Shared service data: uses shared types (evidence: `services/shared/index.ts`)
- Pronote adapter → Shared service data: implements contracts (evidence: `services/pronote/index.ts`)
- EcoleDirecte adapter → Shared service data: implements contracts (evidence: `services/ecoledirecte/index.ts`)
- Skolengo adapter → Shared service data: implements contracts (evidence: `services/skolengo/index.ts`)
- Service manager → Pronote adapter: dispatches requests (evidence: `services/shared/index.ts`)
- Service manager → EcoleDirecte adapter: dispatches requests (evidence: `services/shared/index.ts`)
- Service manager → Skolengo adapter: dispatches requests (evidence: `services/shared/index.ts`)
- Service manager → Other provider adapters: supports providers (evidence: `services/shared/index.ts`)
- School platforms → Pronote adapter: serves data
- School platforms → EcoleDirecte adapter: serves data
- School platforms → Skolengo adapter: serves data
- Calendar and timetable → Local calendar imports: imports calendars
- Service manager → Calendar and timetable: provides timetable
- Service manager → News: provides news
- Service manager → Attendance: provides attendance
- Service manager → Grades: provides grades (evidence: `app/(tabs)/grades/hooks/useGradesData.ts`)
- Service manager → School cards: provides balances
