# gudluckman/tutr architecture

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

- Interactive diagram: https://gitdiagram.com/gudluckman/tutr
- Repository: https://github.com/gudluckman/tutr

## Overview

Tutr combines a public tutor marketplace with a tutor’s business-management dashboard. Parents or students discover published profiles and send enquiries; tutors register, manage profiles and students, schedule lessons, track payment status, and review earnings. The frontend calls a Spring API, whose services coordinate domain logic and persistence. Google Calendar synchronization is a separate optional integration, and historical CSV earnings contribute to analytics. The README documents these product capabilities; unsampled controller and service internals are represented only at their documented boundaries.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/gudluckman/tutr/blob/main/frontend/src/api/client.ts) (API client), [`frontend/src/pages/dashboard/DashboardLayout.tsx`](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/DashboardLayout.tsx) (Tutor dashboard), [`backend/src/main/java/com/tutr/api/service/GoogleCalendarSyncService.java`](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/GoogleCalendarSyncService.java) (Calendar sync), [`backend/src/main/java/com/tutr/api/service/EnquiryService.java`](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/EnquiryService.java) (Enquiry service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_public_pages["Search and profiles"]
  node_auth_pages["Login and register<br/>[RegisterPage.tsx]"]
  node_dashboard["Tutor dashboard"]
  node_enquiry_page["Enquiry inbox<br/>[EnquiriesPage.tsx]"]
  node_student_page["Student management<br/>[StudentsPage.tsx]"]
  node_lesson_page["Lesson management<br/>[LessonsPage.tsx]"]
  node_earnings_page["Earnings analytics<br/>[EarningsPage.tsx]"]
  node_profile_page["Profile settings"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_market["Marketplace"]
  node_public_controller["Public tutor API"]
  node_enquiry_controller["Enquiry API"]
  node_enquiry_service["Enquiry service"]
end

subgraph group_operations["Tutor operations"]
  node_student_controller["Student API"]
  node_lesson_controller["Lesson API"]
  node_analytics_controller["Analytics API"]
  node_profile_controller["Tutor profile API"]
  node_student_service["Student service"]
  node_lesson_service["Lesson service<br/>[LessonService.java]"]
  node_analytics_service["Analytics service"]
  node_profile_service["Profile service"]
end

subgraph group_backend["API services"]
  node_auth_controller["Authentication API"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["External integrations"]
  node_calendar_controller["Calendar API"]
  node_image_storage["Profile image storage"]
  node_calendar_service["Calendar sync"]
end

node_parents(("Parents and students"))
node_tutors(("Tutors"))
node_google_calendar["Google Calendar"]

node_parents -->|"searches profiles"| node_public_pages
node_parents -->|"sends enquiry"| node_public_pages
node_tutors -->|"registers"| node_auth_pages
node_tutors -->|"manages business"| node_dashboard
node_tutors -->|"edits profile"| node_profile_page
node_public_pages -->|"requests tutors"| node_api_client
node_auth_pages -->|"authenticates"| node_api_client
node_dashboard -->|"opens inbox"| node_enquiry_page
node_dashboard -->|"manages students"| node_student_page
node_dashboard -->|"manages lessons"| node_lesson_page
node_dashboard -->|"reviews earnings"| node_earnings_page
node_enquiry_page -->|"updates enquiries"| node_api_client
node_student_page -->|"requests students"| node_api_client
node_lesson_page -->|"requests lessons"| node_api_client
node_earnings_page -->|"requests analytics"| node_api_client
node_profile_page -->|"updates profile"| node_api_client
node_api_client -->|"calls API"| node_public_controller
node_api_client -->|"calls API"| node_auth_controller
node_api_client -->|"calls API"| node_enquiry_controller
node_api_client -->|"calls API"| node_student_controller
node_api_client -->|"calls API"| node_lesson_controller
node_api_client -->|"calls API"| node_analytics_controller
node_api_client -->|"calls API"| node_profile_controller
node_public_controller -->|"reads profiles"| node_postgres
node_auth_controller -->|"delegates auth"| node_auth_service
node_auth_service -->|"reads and writes users"| node_postgres
node_enquiry_controller -->|"delegates enquiries"| node_enquiry_service
node_enquiry_service -->|"converts enquiry"| node_student_service
node_enquiry_service -->|"persists enquiries"| node_postgres
node_student_controller -->|"delegates students"| node_student_service
node_student_service -->|"persists students"| node_postgres
node_lesson_controller -->|"delegates lessons"| node_lesson_service
node_lesson_service -->|"persists lessons"| node_postgres
node_analytics_controller -->|"delegates analytics"| node_analytics_service
node_analytics_service -->|"reads earnings"| node_postgres
node_profile_controller -->|"delegates profile"| node_profile_service
node_profile_service -->|"persists profile"| node_postgres
node_profile_service -->|"stores image"| node_image_storage
node_image_storage -.->|"uploads image"| node_google_calendar
node_lesson_service -->|"syncs lesson"| node_calendar_service
node_calendar_controller -->|"manages connection"| node_calendar_service
node_calendar_service -.->|"syncs events"| node_google_calendar
node_calendar_service -->|"stores sync state"| node_postgres

click node_public_pages "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/public/TutorSearchPage.tsx"
click node_auth_pages "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/auth/RegisterPage.tsx"
click node_dashboard "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/DashboardLayout.tsx"
click node_enquiry_page "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/EnquiriesPage.tsx"
click node_student_page "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/StudentsPage.tsx"
click node_lesson_page "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/LessonsPage.tsx"
click node_earnings_page "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/EarningsPage.tsx"
click node_profile_page "https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/ProfileSettingsPage.tsx"
click node_api_client "https://github.com/gudluckman/tutr/blob/main/frontend/src/api/client.ts"
click node_public_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/PublicTutorController.java"
click node_enquiry_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/EnquiryController.java"
click node_auth_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/AuthController.java"
click node_student_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/StudentController.java"
click node_lesson_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/LessonController.java"
click node_analytics_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/AnalyticsController.java"
click node_profile_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/TutorProfileController.java"
click node_calendar_controller "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/GoogleCalendarController.java"
click node_auth_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/AuthService.java"
click node_enquiry_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/EnquiryService.java"
click node_student_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/StudentService.java"
click node_lesson_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/LessonService.java"
click node_analytics_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/AnalyticsService.java"
click node_profile_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/TutorProfileService.java"
click node_image_storage "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/ProfileImageStorageService.java"
click node_calendar_service "https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/GoogleCalendarSyncService.java"

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_public_pages,node_auth_pages,node_dashboard,node_enquiry_page,node_student_page,node_lesson_page,node_earnings_page,node_profile_page,node_api_client toneBlue
class node_public_controller,node_enquiry_controller,node_enquiry_service toneAmber
class node_student_controller,node_lesson_controller,node_analytics_controller,node_profile_controller,node_student_service,node_lesson_service,node_analytics_service,node_profile_service toneMint
class node_auth_controller,node_auth_service,node_postgres toneRose
class node_calendar_controller,node_image_storage,node_calendar_service,node_parents,node_tutors,node_google_calendar toneIndigo
```

## Components

### Web experience

- [Search and profiles](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/public/TutorSearchPage.tsx): `frontend/src/pages/public/TutorSearchPage.tsx`
- [Login and register](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/auth/RegisterPage.tsx): `frontend/src/pages/auth/RegisterPage.tsx`
- [Tutor dashboard](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/DashboardLayout.tsx): `frontend/src/pages/dashboard/DashboardLayout.tsx`
- [Enquiry inbox](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/EnquiriesPage.tsx): `frontend/src/pages/dashboard/EnquiriesPage.tsx`
- [Student management](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/StudentsPage.tsx): `frontend/src/pages/dashboard/StudentsPage.tsx`
- [Lesson management](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/LessonsPage.tsx): `frontend/src/pages/dashboard/LessonsPage.tsx`
- [Earnings analytics](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/EarningsPage.tsx): `frontend/src/pages/dashboard/EarningsPage.tsx`
- [Profile settings](https://github.com/gudluckman/tutr/blob/main/frontend/src/pages/dashboard/ProfileSettingsPage.tsx): `frontend/src/pages/dashboard/ProfileSettingsPage.tsx`
- [API client](https://github.com/gudluckman/tutr/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Marketplace

- [Public tutor API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/PublicTutorController.java): `backend/src/main/java/com/tutr/api/controller/PublicTutorController.java`
- [Enquiry API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/EnquiryController.java): `backend/src/main/java/com/tutr/api/controller/EnquiryController.java`
- [Enquiry service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/EnquiryService.java): `backend/src/main/java/com/tutr/api/service/EnquiryService.java`

### Tutor operations

- [Student API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/StudentController.java): `backend/src/main/java/com/tutr/api/controller/StudentController.java`
- [Lesson API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/LessonController.java): `backend/src/main/java/com/tutr/api/controller/LessonController.java`
- [Analytics API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/AnalyticsController.java): `backend/src/main/java/com/tutr/api/controller/AnalyticsController.java`
- [Tutor profile API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/TutorProfileController.java): `backend/src/main/java/com/tutr/api/controller/TutorProfileController.java`
- [Student service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/StudentService.java): `backend/src/main/java/com/tutr/api/service/StudentService.java`
- [Lesson service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/LessonService.java): `backend/src/main/java/com/tutr/api/service/LessonService.java`
- [Analytics service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/AnalyticsService.java): `backend/src/main/java/com/tutr/api/service/AnalyticsService.java`
- [Profile service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/TutorProfileService.java): `backend/src/main/java/com/tutr/api/service/TutorProfileService.java`

### API services

- [Authentication API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/AuthController.java): `backend/src/main/java/com/tutr/api/controller/AuthController.java`
- [Auth service](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/AuthService.java): `backend/src/main/java/com/tutr/api/service/AuthService.java`
- **PostgreSQL**

### External integrations

- [Calendar API](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/controller/GoogleCalendarController.java): `backend/src/main/java/com/tutr/api/controller/GoogleCalendarController.java`
- [Profile image storage](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/ProfileImageStorageService.java): `backend/src/main/java/com/tutr/api/service/ProfileImageStorageService.java`
- [Calendar sync](https://github.com/gudluckman/tutr/blob/main/backend/src/main/java/com/tutr/api/service/GoogleCalendarSyncService.java): `backend/src/main/java/com/tutr/api/service/GoogleCalendarSyncService.java`

### Other components

- **Parents and students**
- **Tutors**
- **Google Calendar**

## Connections

- Parents and students → Search and profiles: searches profiles
- Parents and students → Search and profiles: sends enquiry
- Tutors → Login and register: registers
- Tutors → Tutor dashboard: manages business
- Tutors → Profile settings: edits profile
- Search and profiles → API client: requests tutors
- Login and register → API client: authenticates
- Tutor dashboard → Enquiry inbox: opens inbox
- Tutor dashboard → Student management: manages students
- Tutor dashboard → Lesson management: manages lessons
- Tutor dashboard → Earnings analytics: reviews earnings
- Enquiry inbox → API client: updates enquiries
- Student management → API client: requests students
- Lesson management → API client: requests lessons
- Earnings analytics → API client: requests analytics
- Profile settings → API client: updates profile
- API client → Public tutor API: calls API
- API client → Authentication API: calls API
- API client → Enquiry API: calls API
- API client → Student API: calls API
- API client → Lesson API: calls API
- API client → Analytics API: calls API
- API client → Tutor profile API: calls API
- Public tutor API → PostgreSQL: reads profiles
- Authentication API → Auth service: delegates auth
- Auth service → PostgreSQL: reads and writes users
- Enquiry API → Enquiry service: delegates enquiries
- Enquiry service → Student service: converts enquiry
- Enquiry service → PostgreSQL: persists enquiries
- Student API → Student service: delegates students
- Student service → PostgreSQL: persists students
- Lesson API → Lesson service: delegates lessons
- Lesson service → PostgreSQL: persists lessons
- Analytics API → Analytics service: delegates analytics
- Analytics service → PostgreSQL: reads earnings
- Tutor profile API → Profile service: delegates profile
- Profile service → PostgreSQL: persists profile
- Profile service → Profile image storage: stores image
- Profile image storage → Google Calendar: uploads image
- Lesson service → Calendar sync: syncs lesson
- Calendar API → Calendar sync: manages connection
- Calendar sync → Google Calendar: syncs events
- Calendar sync → PostgreSQL: stores sync state