Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
435 lines (353 loc) · 9.08 KB

ARCHITECTURE.md

File metadata and controls

435 lines (353 loc) · 9.08 KB

Collaborado Architecture Documentation

This document provides architectural diagrams and schemas for the Collaborado application.

Table of Contents

  1. System Architecture
  2. Database Schema (ERD)
  3. Class Diagrams
  4. Request Flow
  5. Authentication Flow

System Architecture

High-Level System Diagram

flowchart TB
    subgraph Client["Client Layer"]
        Browser["Web Browser"]
    end

    subgraph External["External Services"]
        Google["Google OAuth 2.0"]
    end

    subgraph Application["Application Layer (Rails 8)"]
        Puma["Puma Web Server"]
        
        subgraph Controllers["Controllers"]
            HomeC["HomeController"]
            SessionsC["SessionsController"]
            DashboardC["DashboardController"]
            CoursesC["CoursesController"]
            ChannelsC["ChannelsController"]
            PostsC["PostsController"]
            ProfilesC["ProfilesController"]
        end

        subgraph Models["Models"]
            User["User"]
            Course["Course"]
            Channel["Channel"]
            Post["Post"]
            Comment["Comment"]
            Enrollment["CourseEnrollment"]
            Upvotes["PostUpvote / CommentUpvote"]
        end

        subgraph Views["Views (ERB)"]
            Templates["HTML Templates"]
            Partials["Shared Partials"]
        end
    end

    subgraph Database["Database Layer"]
        SQLite["SQLite (Dev/Test)"]
        PostgreSQL["PostgreSQL (Production)"]
    end

    Browser --> Puma
    Browser --> Google
    Google --> SessionsC
    Puma --> Controllers
    Controllers --> Models
    Controllers --> Views
    Models --> SQLite
    Models --> PostgreSQL
Loading

Component Architecture

flowchart LR
    subgraph Frontend["Frontend"]
        HTML["HTML/ERB"]
        CSS["SCSS Stylesheets"]
        JS["Stimulus.js"]
        Turbo["Turbo (Hotwire)"]
    end

    subgraph Backend["Backend (Rails 8)"]
        Routes["Routes"]
        Controllers["Controllers"]
        Models["Models"]
        Helpers["View Helpers"]
    end

    subgraph Services["Services & Middleware"]
        OmniAuth["OmniAuth (Google OAuth)"]
        Kaminari["Kaminari (Pagination)"]
    end

    subgraph Storage["Data Storage"]
        DB[(Database)]
        Assets["Asset Pipeline (Propshaft)"]
    end

    Frontend --> Routes
    Routes --> Controllers
    Controllers --> Models
    Controllers --> Helpers
    Models --> DB
    CSS --> Assets
    OmniAuth --> Controllers
    Kaminari --> Models
Loading

Database Schema (ERD)

Entity-Relationship Diagram

Database ERD

Schema Overview

erDiagram
    User ||--o{ CourseEnrollment : "enrolls in"
    User ||--o{ Course : "creates"
    User ||--o{ Post : "writes"
    User ||--o{ Comment : "writes"
    User ||--o{ PostUpvote : "gives"
    User ||--o{ CommentUpvote : "gives"
    
    Course ||--o{ CourseEnrollment : "has"
    Course ||--o{ Channel : "contains"
    
    Channel ||--o{ Post : "contains"
    
    Post ||--o{ Comment : "has"
    Post ||--o{ PostUpvote : "receives"
    
    Comment ||--o{ Comment : "replies to"
    Comment ||--o{ CommentUpvote : "receives"

    User {
        integer id PK
        string netid
        string email
        string first_name
        string last_name
        string role
        string provider
        string google_uid
        datetime last_login_at
    }

    Course {
        integer id PK
        string name
        string crn
        string department
        string course_code
        string instructor
        text description
        integer created_by FK
    }

    CourseEnrollment {
        integer id PK
        integer user_id FK
        integer course_id FK
        string role
    }

    Channel {
        integer id PK
        string name
        text description
        integer course_id FK
    }

    Post {
        integer id PK
        string title
        text content
        string type
        boolean resolved
        integer upvote_count
        integer channel_id FK
        integer user_id FK
    }

    Comment {
        integer id PK
        text content
        integer upvote_count
        integer post_id FK
        integer user_id FK
        integer parent_id FK
    }

    PostUpvote {
        integer id PK
        integer post_id FK
        integer user_id FK
    }

    CommentUpvote {
        integer id PK
        integer comment_id FK
        integer user_id FK
    }
Loading

Class Diagrams

Model Class Diagram

Models Class Diagram

Controller Class Diagram

Controllers Class Diagram

Model Relationships

classDiagram
    class User {
        +String netid
        +String email
        +String first_name
        +String last_name
        +String role
        +full_name()
        +from_google(auth_hash)
    }

    class Course {
        +String name
        +String crn
        +String department
        +String course_code
        +String instructor
        +Text description
        +full_code()
        +enrolled_by?(user)
    }

    class Channel {
        +String name
        +Text description
    }

    class Post {
        +String title
        +Text content
        +String type
        +Boolean resolved
        +Integer upvote_count
        +question?()
        +note?()
    }

    class Comment {
        +Text content
        +Integer upvote_count
    }

    class CourseEnrollment {
        +String role
    }

    User "1" --> "*" CourseEnrollment
    User "1" --> "*" Post
    User "1" --> "*" Comment
    Course "1" --> "*" CourseEnrollment
    Course "1" --> "*" Channel
    Channel "1" --> "*" Post
    Post "1" --> "*" Comment
Loading

Request Flow

Typical Page Request

sequenceDiagram
    participant B as Browser
    participant R as Router
    participant C as Controller
    participant M as Model
    participant V as View
    participant DB as Database

    B->>R: HTTP Request
    R->>C: Route to Action
    C->>M: Query Data
    M->>DB: SQL Query
    DB-->>M: Results
    M-->>C: Model Objects
    C->>V: Render Template
    V-->>C: HTML
    C-->>B: HTTP Response
Loading

Post Creation Flow

sequenceDiagram
    participant U as User
    participant PC as PostsController
    participant P as Post Model
    participant Ch as Channel Model
    participant DB as Database

    U->>PC: POST /channels/:id/posts
    PC->>PC: Authenticate User
    PC->>Ch: Find Channel
    Ch->>DB: SELECT channel
    DB-->>Ch: Channel data
    PC->>P: Build new Post
    P->>P: Validate
    P->>DB: INSERT post
    DB-->>P: Created post
    PC-->>U: Redirect to Channel
Loading

Authentication Flow

Google OAuth 2.0 Flow

sequenceDiagram
    participant U as User
    participant App as Collaborado
    participant G as Google OAuth

    U->>App: Click "Sign In with Google"
    App->>G: Redirect to Google
    G->>U: Show Login Form
    U->>G: Enter Credentials
    G->>G: Validate @tamu.edu domain
    G->>App: Callback with Auth Token
    App->>App: Create/Find User
    App->>App: Create Session
    App-->>U: Redirect to Dashboard
Loading

Session Management

flowchart TD
    A[User visits page] --> B{Logged in?}
    B -->|Yes| C[Show Dashboard]
    B -->|No| D[Show Landing Page]
    
    D --> E[Click Sign In]
    E --> F[Google OAuth]
    F --> G{@tamu.edu?}
    G -->|Yes| H[Create Session]
    G -->|No| I[Access Denied]
    
    H --> J{Has Role?}
    J -->|Yes| C
    J -->|No| K[Select Role]
    K --> C
    
    C --> L[User Actions]
    L --> M[Logout]
    M --> D
Loading

Technology Stack

Layer Technology
Frontend HTML, ERB, SCSS, Stimulus.js, Turbo
Backend Ruby 3.4.5, Rails 8.0
Database SQLite (dev/test), PostgreSQL (prod)
Authentication OmniAuth, Google OAuth 2.0
Asset Pipeline Propshaft, Dart Sass
Testing RSpec, Cucumber, FactoryBot
Web Server Puma

Directory Structure

app/
├── controllers/     # Request handling
│   ├── application_controller.rb
│   ├── courses_controller.rb
│   ├── channels_controller.rb
│   ├── posts_controller.rb
│   └── ...
├── models/          # Business logic & data
│   ├── user.rb
│   ├── course.rb
│   ├── channel.rb
│   ├── post.rb
│   └── ...
├── views/           # HTML templates
│   ├── layouts/
│   ├── courses/
│   ├── channels/
│   └── ...
├── helpers/         # View helpers
└── assets/          # CSS, images
    └── stylesheets/

config/
├── routes.rb        # URL routing
├── database.yml     # Database config
└── initializers/    # App configuration

db/
├── schema.rb        # Database schema
├── seeds.rb         # Seed data
└── migrate/         # Migrations

spec/                # RSpec tests
features/            # Cucumber features

Generated with rails-erd, railroady, and Mermaid diagrams