# falaxsa13/turing architecture

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

- Interactive diagram: https://gitdiagram.com/falaxsa13/turing
- Repository: https://github.com/falaxsa13/turing

## Overview

##### File structure
- Top-level artifacts:
- docker-compose.yml & requirements.txt – deployment and dependency info
- Makefile – build/test commands
- NOTION_DATABASE_SCHEMAS.md – Notion database layout
- app/main.py – entrypoint for the HTTP server
- app/api – FastAPI (or similar) route definitions (auth, canvas, notion, sync, health, setup)
- app/auth.py – authentication helper (JWT/OAuth)
- app/core – configuration, constants, dependency injection, logging, exception handling, shared responses
- app/models and app/schemas – Pydantic models (DB or API payloads) and request/response schemas
- app/services – four subdomains:
- canvas – Canvas API client, mappers, data extractors, sync service
- notion – Notion assignment formatter, enhanced assignment manager
- firebase – logging service, user management, configuration constants
- sync – orchestrators for assignment_sync, course_sync, status_service
- app/utils – small helpers (date utilities, Notion helper functions)

##### README for additional insights
- Unfortunately the README only has the project title (“The Turing Project”). We infer the architecture entirely from code.

a. Main components
1. API Layer
- HTTP Server (FastAPI) exposing routes:
- /auth
- /canvas
- /notion
- /sync
- /health
- /setup
2. Core Layer
- Configuration, logging, exception handlers, dependency‐injection framework
3. Business / Service Layer
i. Canvas Service
- canvas.client (raw Canvas REST client)
- enhanced_client, data_extractors, course_mapper, sync_service
ii. Notion Service
- assignment_formatter, enhanced_assignment_manager
iii. Firebase Service
- logging_service, user_service, manager (for user data, session data, logging events)
iv. Sync Orchestrator
- course_sync, assignment_sync, status_service
4. External Systems
- Canvas LMS API
- Notion API
- Firebase (Auth & Firestore or Realtime DB)
5. Utilities
- Common helpers (date_utils, notion_helper)

b. Relationships and interactions
1. Client (user or scheduler) → API Layer
2. API Layer routes invoke Core dependencies (auth, config, DB client)
3. Auth route uses Firebase user_service to sign in/up and return JWT
4. Sync route calls Sync Orchestrator → which calls Canvas Service and Notion Service in series:
- Canvas Service fetches courses/assignments from Canvas API
- Data is mapped/formatted → handed off to Notion Service
- Notion Service writes/updates pages/databases via Notion API
- Throughout the flow, Firebase logging_service logs events and status_service updates status in Firebase
5. Setup route seeds initial Notion schemas (using NOTION_DATABASE_SCHEMAS.md)
6. Health route checks external dependencies (Canvas, Notion, Firebase connectivity)

c. Architectural patterns
- Layered architecture (API layer → service layer → external systems)
- Dependency Injection (app/core/dependencies.py)
- Separation of concerns: each external system has its own service module
- Orchestration pattern: sync sub-services coordinate multiple backend services

d. Key technologies
- Python 3.x
- FastAPI (or similar ASGI framework)
- Pydantic for request/response schemas
- Docker Compose for local development
- Firebase (Auth + Firestore/RTDB)
- Canvas REST API & Notion REST API

##### Final recommendations
- Be detailed: capture all four service domains distinctly

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client/Scheduler"]:::external

    subgraph "API Layer"
        main["Main HTTP Server"]:::internal
        authRoute["/auth Route"]:::internal
        canvasRoute["/canvas Route"]:::internal
        notionRoute["/notion Route"]:::internal
        syncRoute["/sync Route"]:::internal
        healthRoute["/health Route"]:::internal
        setupRoute["/setup Route"]:::internal
    end

    subgraph "Core Layer"
        base["base.py"]:::internal
        config["config.py"]:::internal
        constants["constants.py"]:::internal
        dependencies["dependencies.py"]:::internal
        exceptions["exceptions.py"]:::internal
        loggingCore["logging.py"]:::internal
        responses["responses.py"]:::internal
    end

    subgraph "Service Layer"
        subgraph "Canvas Service"
            canvasClient["client.py"]:::internal
            enhancedClient["enhanced_client.py"]:::internal
            canvasConstants["constants.py"]:::internal
            courseMapper["course_mapper.py"]:::internal
            dataExtractors["data_extractors.py"]:::internal
            profDetector["professor_detector.py"]:::internal
            canvasSync["sync_service.py"]:::internal
        end
        subgraph "Notion Service"
            assignmentFormatter["assignment_formatter.py"]:::internal
            enhancedAssignmentMgr["enhanced_assignment_manager.py"]:::internal
        end
        subgraph "Firebase Service"
            fbConstants["constants.py"]:::internal
            loggingService["logging_service.py"]:::internal
            userManager["manager.py"]:::internal
            userService["user_service.py"]:::internal
        end
        subgraph "Sync Orchestrator"
            courseSync["course_sync.py"]:::internal
            assignmentSync["assignment_sync.py"]:::internal
            statusService["status_service.py"]:::internal
        end
    end

    subgraph "Utilities"
        dateUtils["date_utils.py"]:::internal
        notionHelper["notion_helper.py"]:::internal
    end

    subgraph "External Systems"
        canvasAPI["Canvas LMS API"]:::external
        notionAPI["Notion API"]:::external
        firebaseAPI["Firebase (Auth & DB)"]:::external
    end

    %% Data Flows
    Client --> main
    main --> authRoute
    main --> canvasRoute
    main --> notionRoute
    main --> syncRoute
    main --> healthRoute
    main --> setupRoute

    authRoute -->|"use dependencies"| dependencies
    canvasRoute --> dependencies
    notionRoute --> dependencies
    syncRoute --> dependencies
    healthRoute --> dependencies
    setupRoute --> dependencies

    authRoute -->|"authenticate"| userService
    syncRoute --> courseSync
    syncRoute --> assignmentSync
    setupRoute --> enhancedAssignmentMgr

    courseSync --> canvasSync
    assignmentSync --> assignmentFormatter

    canvasSync --> canvasClient
    canvasClient --> canvasAPI
    courseSync --> courseMapper

    assignmentFormatter --> enhancedAssignmentMgr
    enhancedAssignmentMgr --> notionAPI

    canvasSync --> loggingService
    enhancedAssignmentMgr --> loggingService
    statusService --> loggingService

    healthRoute -.-> canvasAPI
    healthRoute -.-> notionAPI
    healthRoute -.-> firebaseAPI

    %% Click Events
    click main "https://github.com/falaxsa13/turing/blob/main/app/main.py"
    click authRoute "https://github.com/falaxsa13/turing/blob/main/app/api/auth.py"
    click canvasRoute "https://github.com/falaxsa13/turing/blob/main/app/api/canvas.py"
    click notionRoute "https://github.com/falaxsa13/turing/blob/main/app/api/notion.py"
    click syncRoute "https://github.com/falaxsa13/turing/blob/main/app/api/sync.py"
    click healthRoute "https://github.com/falaxsa13/turing/blob/main/app/api/health.py"
    click setupRoute "https://github.com/falaxsa13/turing/blob/main/app/api/setup.py"

    click base "https://github.com/falaxsa13/turing/blob/main/app/core/base.py"
    click config "https://github.com/falaxsa13/turing/blob/main/app/core/config.py"
    click constants "https://github.com/falaxsa13/turing/blob/main/app/core/constants.py"
    click dependencies "https://github.com/falaxsa13/turing/blob/main/app/core/dependencies.py"
    click exceptions "https://github.com/falaxsa13/turing/blob/main/app/core/exceptions.py"
    click loggingCore "https://github.com/falaxsa13/turing/blob/main/app/core/logging.py"
    click responses "https://github.com/falaxsa13/turing/blob/main/app/core/responses.py"

    click canvasClient "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/client.py"
    click enhancedClient "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/enhanced_client.py"
    click canvasConstants "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/constants.py"
    click courseMapper "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/course_mapper.py"
    click dataExtractors "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/data_extractors.py"
    click profDetector "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/professor_detector.py"
    click canvasSync "https://github.com/falaxsa13/turing/blob/main/app/services/canvas/sync_service.py"

    click assignmentFormatter "https://github.com/falaxsa13/turing/blob/main/app/services/notion/assignment_formatter.py"
    click enhancedAssignmentMgr "https://github.com/falaxsa13/turing/blob/main/app/services/notion/enhanced_assignment_manager.py"

    click fbConstants "https://github.com/falaxsa13/turing/blob/main/app/services/firebase/constants.py"
    click loggingService "https://github.com/falaxsa13/turing/blob/main/app/services/firebase/logging_service.py"
    click userManager "https://github.com/falaxsa13/turing/blob/main/app/services/firebase/manager.py"
    click userService "https://github.com/falaxsa13/turing/blob/main/app/services/firebase/user_service.py"

    click courseSync "https://github.com/falaxsa13/turing/blob/main/app/services/sync/course_sync.py"
    click assignmentSync "https://github.com/falaxsa13/turing/blob/main/app/services/sync/assignment_sync.py"
    click statusService "https://github.com/falaxsa13/turing/blob/main/app/services/sync/status_service.py"

    click dateUtils "https://github.com/falaxsa13/turing/blob/main/app/utils/date_utils.py"
    click notionHelper "https://github.com/falaxsa13/turing/blob/main/app/utils/notion_helper.py"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6,color:#000
    classDef external fill:#CFFFCF,stroke:#228B22,color:#000
    classDef dashed stroke-dasharray: 5 5
```
