# ohsync/ohsync architecture

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

- Interactive diagram: https://gitdiagram.com/ohsync/ohsync
- Repository: https://github.com/ohsync/ohsync

## Overview

##### Project Type and Purpose
- OHsync is a full-stack web application.
- Its primary goal is to manage and display office hours for UF professors/TAs, with a clear separation between the backend API handling business logic (including office hour management, search, LLM integration, etc.) and the frontend user interface presented in a React-like framework.
- The README and file tree confirm the separation into “apps/backend” and “apps/frontend” with dedicated entry points (index.ts for backend, App.tsx for frontend).

##### Analyzing the File Structure
- The project is organized under a monorepo structure with a clear division into two main components:
a. Backend (located in apps/backend)
- Contains a structured API that follows an MVC-like pattern with controllers, routers, and services (for canvas, healthCheck, llm, search, user endpoints).
- Uses middleware components (adminAuth, cache, rateLimiter, errorHandler, uflAuth) to handle common concerns.
- Incorporates a database layer with repositories, migration scripts (using Knex), seeds, and initialization scripts, indicating a relational database design.
- Includes utility functions and schemas for data validation, suggesting type safety and schema consistency.
b. Frontend (located in apps/frontend)
- A React/TSX-based application (entry point: App.tsx).
- Components organized into UI and business-specific components (e.g., account-button, feedback-dialog, tables).
- Uses external configuration such as Tailwind CSS (tailwind.config.js) for styling and a modern bundler (vite).

- Frontend: The user interface (React, UI components, pages, and services).
- Backend: The RESTful API providing endpoints for office hours, user management, canvas, search, LLM integration, and more.
- Database: The underlying relational database managed via migrations and seeds, supporting data models like users, courses, office hours, feedback, audit logs, etc.
- External/Supporting Services:
- Deployment tooling (Docker, Dockerfile, docker-compose, GitHub workflows for CI/CD).
- Package management via Bun.
- Interactions:
- Backend to the Database to show data persistence and retrieval through repositories and migration tools.
- Middleware in the backend as layers that intercept and process requests/responses.

##### Important Architectural Patterns and Technologies
- Layered/MVC style used in the backend:
- Controllers handle HTTP requests.
- Routers define the endpoints and delegate to controllers.
- Services contain the business logic.
- Middleware handles cross-cutting concerns like authentication, error handling, and rate limiting.
- For the frontend:
- Component-based structure that leverages React’s strengths in modular UI development.
- Integration with tools and frameworks:
- Knex for database migrations and seeds.
- Bun for dependency management and running scripts.
- Docker for containerization, ensuring environment consistency.
- Tailwind CSS for styling.
- Version control and CI/CD pipelines configured via GitHub worklows.

##### Instructing the Principal Software Engineer
- Component is clearly labeled:
- "Frontend (React, Vite)" for apps/frontend.
- "Backend APIs (Express/Router Pattern, Business Logic)" for apps/backend.
- "Database (Relational, managed via Knex migrations/seeds)".
- Data flow from the frontend to backend, and from backend to the database.
- The middleware chain in the backend (routing requests via error handling, rate limiter, and authentication middleware).
- Presentation layer (Frontend), service layer (Backend), and persistence layer (Database).
- Deployment and orchestration details as side notes:
- Docker integration via Dockerfile and docker-compose.
- CI/CD integration with GitHub actions.
- Bun commands for running services and managing the database.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend Zone"
        FE1["Frontend Entry (App.tsx)"]:::frontend
        FE2["Frontend Directory"]:::frontend
        FE1 -->|"includes"| FE2
    end

    %% Backend Zone
    subgraph "Backend Zone"
        BE1["Backend Entry (index.ts)"]:::backend
        BE2["Backend APIs (Controllers, Services)"]:::backend
        BE1 -->|"calls"| BE2
        MW["Middleware (Auth,Cache,RateLimiter,etc.)"]:::middleware
        BE1 -->|"passes through"| MW
        MW -->|"forwards to"| BE2
        %% Utilities Subgraph inside Backend
        subgraph "Utilities"
            SCHEMA["Validation Schemas"]:::utility
            UTILS["Utility Functions"]:::utility
            SCHEMA --> UTILS
        end
        BE2 -->|"uses"| SCHEMA
    end

    %% Persistence Zone
    subgraph "Persistence Zone"
        DB["Database (Knex, Migrations,Seeds)"]:::database
    end

    %% Deployment & CI/CD Zone
    subgraph "Deployment & CI/CD"
        DEPLOY1["Docker & Compose"]:::deployment
        DEPLOY2["CI/CD (GitHub Workflows)"]:::deployment
        DEPLOY1 --> DEPLOY2
    end

    %% Package Management & Build Tools Zone
    subgraph "Package Management & Build Tools"
        PKG["Root Package Management"]:::pkg
        FTW["Frontend Tailwind Config"]:::pkg
        BBG["Backend Build Config"]:::pkg
        PKG --> FTW
        FTW --> BBG
    end

    %% Interconnections between zones
    FE1 -->|"HTTP_Request"| BE1
    BE2 -->|"DB_Query"| DB

    %% Influence of Package Management & Deployment on Frontend and Backend
    PKG -.-> FE1
    PKG -.-> BE1
    DEPLOY1 -.-> FE1
    DEPLOY1 -.-> BE1
    DEPLOY1 -.-> DB

    %% Click Events
    click FE1 "https://github.com/ohsync/ohsync/blob/main/apps/frontend/src/App.tsx"
    click FE2 "https://github.com/ohsync/ohsync/tree/main/apps/frontend"
    click BE1 "https://github.com/ohsync/ohsync/blob/main/apps/backend/src/index.ts"
    click BE2 "https://github.com/ohsync/ohsync/tree/main/apps/backend/src/api"
    click MW "https://github.com/ohsync/ohsync/tree/main/apps/backend/src/common/middleware"
    click DB "https://github.com/ohsync/ohsync/tree/main/apps/backend/src/database"
    click SCHEMA "https://github.com/ohsync/ohsync/tree/main/apps/backend/src/common/schemas"
    click UTILS "https://github.com/ohsync/ohsync/tree/main/apps/backend/src/common/utils"
    click DEPLOY1 "https://github.com/ohsync/ohsync/tree/main/Dockerfile"
    click DEPLOY2 "https://github.com/ohsync/ohsync/tree/main/.github/workflows"
    click PKG "https://github.com/ohsync/ohsync/blob/main/package.json"
    click FTW "https://github.com/ohsync/ohsync/blob/main/apps/frontend/tailwind.config.js"
    click BBG "https://github.com/ohsync/ohsync/blob/main/apps/backend/biome.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef middleware fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef deployment fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef pkg fill:#fefefe,stroke:#6f42c1,stroke-width:2px;
```
