# ebertmi/webbox architecture

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

- Interactive diagram: https://gitdiagram.com/ebertmi/webbox
- Repository: https://github.com/ebertmi/webbox

## Overview

##### Project Overview and Purpose
- Type: Web-based editor with support for secure remote code execution (“sourcebox”), implemented as a full-stack web application.
- Purpose: It lets users (students and admins) interact with code examples, documents (using the IPYNB standard), and presentations. The app supports multiple client applications (IDE, dashboard/administration, notebook/presentation) and uses websockets for real-time event tracking.

##### Main Components
a. Client-Side Applications:
- IDE: A React-based coding environment located in directories such as client/js, common/components/ide, and common/models/project.
- Dashboard/Administration: React and Redux based client (see common/components/admin, common/containers/admin) which is also isomorphically rendered from the server.
- Notebook & Presentation: React-based implementations using Immutable.js; referenced in common/components/notebook, common/components/presentation.
b. Server-Side:
- API/Controllers: Structured under lib/controllers (for authentication, courses, documents, dashboards, etc.), which tie the requests (defined via routes in lib/routes and common/route) to the corresponding business logic.
- Templating & Views: Uses the Jade engine (files in lib/views) to render pages for server-side responses.
- Websocket/Realtime Communication: Handled by lib/controllers/websocket.js and configuration in the server startup (webbox.babel.js) to allow bidirectional communication.
- Command-Line Interface (CLI): Tools under bin/ (e.g., cli.js) that allow administrative user management.
c. Database:
- RethinkDB: The application’s data store for documents, code examples, and user data. The models in both common/models and lib/models are built using the Thinky ORM to interact with RethinkDB.
- Migration scripts (migrations folder) are also used to manage database schema changes.
d. Other Key Integrations:
- Configuration: Provided through the config module with multiple JSON files (default, development, production) and a custom config module in config/webbox.config.js.
- Authentication & Authorization: Handled via various auth files in lib/auth and checks in lib/roles.
- Email and Notification: Implemented via lib/mail (templates and utilities).

##### Relationships and Interactions
- The client side makes HTTP requests to RESTful API endpoints (as defined in lib/api) and establishes websocket connections (lib/controllers/websocket) with the server.
- The server’s controllers process incoming requests, interact with the models (via Thinky), and render responses (using Jade templates or JSON for API responses).
- The separation between the three clients creates clear boundaries in communication. For example, the IDE uses a custom model (EventEmitter-based) to notify changes, whereas the Notebook/Presentation leverage Immutable.js.
- A migration component is positioned as a utility that touches the database for schema updates.
- The CLI becomes a side component that allows for administrative operations away from the main HTTP request flow.

##### Architectural Patterns and Designs
- MVC-Style: The structure clearly separates routes, controllers (lib/controllers), and views/templates (lib/views). Models using Thinky encapsulate the business logic.
- Real-time Communication: The use of websockets to push events between server and client.
- Modular Frontend Applications: Different client apps (IDE, dashboard, notebook/presentation) share common React components (under common/components) yet have distinct models (e.g., using plain objects versus Immutable.js).
- Dependency Injection & Configuration: Use of the config module to allow environment-specific configuration.

##### Detail
- Do not over-simplify the components. Instead separate even minor utilities (migration scripts, authentication modules, web socket handling) if their interactions are critical for understanding the overall architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Applications
    subgraph "Client Applications"
        IDE["IDE (React)"]:::client
        Dashboard["Dashboard/Admin (React/Redux)"]:::client
        subgraph "Notebook & Presentation"
            Notebook["Notebook (Immutable.js)"]:::client
            Presentation["Presentation (Immutable.js)"]:::client
        end
    end

    %% Server-Side Components
    subgraph "Server-Side"
        API["API/Controllers"]:::server
        Templating["Templating Engine (Jade)"]:::server
        Websocket["Websocket Service"]:::server
        Auth["Authentication/Authorization"]:::server
        Config["Configuration Module"]:::server
        Email["Email/Notification"]:::server
        CLI["CLI Tools"]:::server
        Models["Database & Models (Thinky ORM)"]:::server
    end

    %% Database Layer
    Database["ReThinkDB"]:::database

    %% Relationships from Client to Server (HTTP Requests)
    IDE -->|"HTTPRequests"| API
    Dashboard -->|"HTTPRequests"| API
    Notebook -->|"HTTPRequests"| API
    Presentation -->|"HTTPRequests"| API

    %% Websocket Communication (Bidirectional between IDE and Server)
    IDE <-->|"Realtime"| Websocket

    %% Server internal communications
    API -->|"RenderPages"| Templating
    API -->|"DatabaseOps"| Models
    API -->|"Uses"| Config
    API -->|"Uses"| Auth
    API -->|"Triggers"| Email
    CLI -->|"AdminOps"| Models
    Models -->|"CRUD"| Database

    %% Styling Classes
    classDef client fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef server fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;

    %% Click Events for Client-Side IDE
    click IDE "https://github.com/ebertmi/webbox/blob/master/client/js/index.js"
    click IDE "https://github.com/ebertmi/webbox/blob/master/common/components/ide/Ide.js"
    click IDE "https://github.com/ebertmi/webbox/blob/master/common/components/ide/IdeWrapper.js"
    click IDE "https://github.com/ebertmi/webbox/blob/master/common/models/project/project.js"

    %% Click Events for Client-Side Dashboard/Administration
    click Dashboard "https://github.com/ebertmi/webbox/blob/master/common/components/admin/Course.js"
    click Dashboard "https://github.com/ebertmi/webbox/blob/master/common/components/admin/User.js"
    click Dashboard "https://github.com/ebertmi/webbox/blob/master/common/containers/admin/AdminApp.js"

    %% Click Events for Client-Side Notebook & Presentation
    click Notebook "https://github.com/ebertmi/webbox/blob/master/common/components/notebook/Notebook.js"
    click Presentation "https://github.com/ebertmi/webbox/blob/master/common/components/presentation/Presentation.js"
    click Presentation "https://github.com/ebertmi/webbox/blob/master/common/components/presentation/DefaultWrapper.js"

    %% Click Events for Server-Side API/Controllers
    click API "https://github.com/ebertmi/webbox/blob/master/lib/api/document.js"
    click API "https://github.com/ebertmi/webbox/blob/master/lib/api/course.js"
    click API "https://github.com/ebertmi/webbox/blob/master/lib/controllers/auth.js"
    click API "https://github.com/ebertmi/webbox/blob/master/lib/controllers/document.js"

    %% Click Events for Templating & Views
    click Templating "https://github.com/ebertmi/webbox/blob/master/lib/views/index.jade"
    click Templating "https://github.com/ebertmi/webbox/blob/master/lib/views/login.jade"

    %% Click Events for Websocket/Realtime Communication
    click Websocket "https://github.com/ebertmi/webbox/blob/master/lib/controllers/websocket.js"
    click Websocket "https://github.com/ebertmi/webbox/blob/master/lib/routes/websocket.js"
    click Websocket "https://github.com/ebertmi/webbox/blob/master/webbox.babel.js"

    %% Click Events for Command-Line Interface (CLI)
    click CLI "https://github.com/ebertmi/webbox/blob/master/bin/cli.js"
    click CLI "https://github.com/ebertmi/webbox/blob/master/bin/_cli.js"

    %% Click Events for Database & Models
    click Models "https://github.com/ebertmi/webbox/blob/master/common/models/annotation.js"
    click Models "https://github.com/ebertmi/webbox/blob/master/lib/models/document.js"
    click Models "https://github.com/ebertmi/webbox/blob/master/lib/models/user.js"
    click Models "https://github.com/ebertmi/webbox/tree/master/migrations"

    %% Click Events for Configuration
    click Config "https://github.com/ebertmi/webbox/blob/master/config/default.json"
    click Config "https://github.com/ebertmi/webbox/blob/master/config/webbox.config.js"

    %% Click Events for Authentication & Authorization
    click Auth "https://github.com/ebertmi/webbox/blob/master/lib/auth/base.js"
    click Auth "https://github.com/ebertmi/webbox/blob/master/lib/auth/simple.js"
    click Auth "https://github.com/ebertmi/webbox/blob/master/lib/roles/checks.js"

    %% Click Events for Email and Notification
    click Email "https://github.com/ebertmi/webbox/blob/master/lib/mail/mailservice.js"
    click Email "https://github.com/ebertmi/webbox/blob/master/lib/mail/forgot_password_template.js"
```
