# tutors-sdk/tutors architecture

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

- Interactive diagram: https://gitdiagram.com/tutors-sdk/tutors
- Repository: https://github.com/tutors-sdk/tutors

## Overview

##### Project Type and Purpose
- This project is a SvelteKit web application that serves as the Tutors Reader—a system that presents learning courses generated from learning content. Its purpose is to display courses in an intuitive web interface while integrating various modular services (such as authentication, course management, community interactions, theming, and markdown processing).

##### File Structure
- The project follows a modular organization. At the top level, you see configuration files (.env, package.json, etc.), GitHub workflow configurations, and TypeScript and Svelte config files.
- The core functionality is contained in the src folder, which further splits into:
- lib: Contains further separation into:
⁃ Services: Divided into subcategories (base, community, connect, course, markdown, themes) – each encapsulating the business logic and external integrations for different aspects of the app.
⁃ UI: Comprises Svelte components for general page elements (navigators, components, learning object renderers, etc.) that handle the presentation layer.

##### Key Components and Relationships
a. Main Components:
- Frontend Application (SvelteKit App):
- Routes and Layouts: Provide the URL structure and overall organization, with segregated segments (auth, course-reader, home, live).
- Global UI: The page wrappers (app.html, app.css), static assets, and main application templates.
- Service Layer:
- Base Services: Provide low-level utilities such as supabase-client initialization.
- Community Services: Handle analytics, catalogue, live interactions, and presence features.
- Services: Manage user connections, authentication (including GitHub login) and profile handling.
- Course Services: Deal with course-specific functionalities such as course management, learning object (LO) processing, live lab interactions, and search utilities.
- Markdown Services: Transform and process Markdown content.
- UI Components:
- Navigators (layout, buttons, footers): Organize navigation and control within the reader interface.
- Learning Object Components: Render course content like videos, labs, talks, etc.

b. Relationships and Interactions:
- The SvelteKit routing layer directs user requests to specific page layouts and components.
- Each route (e.g., for course reading or authentication) interacts with the service layer to fetch or process data (e.g., course details, user session data, content markdown conversion, etc.).
- The UI components consume data from the service layer and render interactive experiences.
- Utilities such as the supabase-client (found in the base utils) indicate external integration for data storage or user management.
- The theming and markdown systems work in tandem with UI elements, allowing the app to adapt its presentation based on context or user settings.

##### Architectural Patterns and Design Principles
- Modular & Layered Architecture: The project is clearly partitioned into UI components, service modules, and configuration layers, enabling separation of concerns.
- Microservice-like Module Separation: Even though it is a monolithic frontend, each service (community, connect, course, markdown, themes) acts as an independent module that can be maintained or replaced.
- Component-Driven UI: Svelte components and pages are organized in a fine-grained manner (e.g., learning objects broken into content, layout, structure) promoting reuse and maintainability.
- External Integrations: There are connections to external systems (such as Supabase for database/authentication services).

##### Elements
- Use clear labels: Each rectangle or module should be named (e.g., “Routes (course-reader, auth, home, live)”, “Service: Course”, “Service: Connect”, “UI: Navigators”, etc.).
- How the Routes layer sends requests or passes data to the Service Modules.
- How the Service Modules feed data into the UI Components.
- Feedback loops (e.g., user actions triggering events back into service utilities).
- External systems (like Supabase) as an external dependency node linked to the base utilities.

##### Putting It All Together
- Under the application, branch out the service modules (grouping by subfolders under src/lib/services) that illustrate how each area is responsible for functionalities (e.g., Course, Connect, Community, Markdown, Themes).
- Demonstrate the flow: User Interaction → Routing → UI Components → Service Calls → (External integrations such as Supabase).

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    subgraph "Frontend Application (SvelteKit)"
        R["Routes (auth,course-reader,home,live)"]:::routes
        U["UI Components"]:::ui
    end
    subgraph "Service Layer"
        SBase["Service: Base"]:::service
        SCommunity["Service: Community"]:::service
        SConnect["Service: Connect"]:::service
        SCourse["Service: Course"]:::service
        SMarkdown["Service: Markdown"]:::service
        SThemes["Service: Themes"]:::service
    end
    Ext["Supabase"]:::external

    User -->|"requests"| R
    R -->|"calls_base"| SBase
    R -->|"calls_community"| SCommunity
    R -->|"calls_connect"| SConnect
    R -->|"calls_course"| SCourse
    R -->|"calls_markdown"| SMarkdown
    R -->|"calls_themes"| SThemes
    SBase -->|"returns_data"| U
    SCommunity -->|"returns_data"| U
    SConnect -->|"returns_data"| U
    SCourse -->|"returns_data"| U
    SMarkdown -->|"returns_data"| U
    SThemes -->|"returns_data"| U
    SBase -->|"uses"| Ext
    User ---|"interacts"| U

    click R "https://github.com/tutors-sdk/tutors/tree/development/src/routes"
    click U "https://github.com/tutors-sdk/tutors/tree/development/src/lib/ui"
    click SBase "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/base"
    click SCommunity "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/community"
    click SConnect "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/connect"
    click SCourse "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/course"
    click SMarkdown "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/markdown"
    click SThemes "https://github.com/tutors-sdk/tutors/tree/development/src/lib/services/themes"

    classDef user fill:#ffddcc,stroke:#d2691e,stroke-width:2px
    classDef routes fill:#cce5ff,stroke:#3366cc,stroke-width:2px
    classDef ui fill:#ffe5b4,stroke:#ff8c00,stroke-width:2px
    classDef service fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    classDef external fill:#f0e68c,stroke:#b8860b,stroke-width:2px
```
