# ellgreen/thoughts architecture

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

- Interactive diagram: https://gitdiagram.com/ellgreen/thoughts
- Repository: https://github.com/ellgreen/thoughts

## Overview

##### Project Type and Purpose
- Thoughts is a self-hosted, full-stack web application for facilitating retrospectives. It supports features like authentication, managing retrospectives (with tasks, notes, votes, etc.), GIF integration (via Tenor), and live updates.
- The README and file tree clearly indicate separation between the UI (built with TypeScript/React, Vite, and Tailwind CSS) and the backend (written in Go) that manages business logic, data access, and real-time updates.

##### Main Components
a. Frontend (UI):
- UI folder as the “Frontend” component.
- That it is built with modern web technologies (React, TypeScript, Vite, Tailwind CSS) and is responsible for rendering the retrospectives, handling user inputs, and managing live updates from the backend.
- Connections to API endpoints and the socket/websocket module (located in ui/src/lib/socket.ts) for real-time communications.

b. Backend (API Server):
- Go application from the cmd/thoughts directory as the “Backend” or “API Server.”
- Responsibility for core functionalities such as authentication, handling REST API requests, business logic (controllers), live events, and processing web socket messages.
- Controllers: (e.g., auth, tasks, retros, notes, votes, gifs) – these modules process incoming requests.
- Data Access Layer (DAL): (located in cmd/thoughts/dal) – abstracts interactions with the database.
- Event System: (from cmd/thoughts/event) – manages live updates and real-time events.
- Session & Socket Modules: (in cmd/thoughts/session and cmd/thoughts/socket) – manage user sessions and socket connections.
- Utility and configuration modules that support other backend functionalities.

c. Database:
- A “Database” component.
- Utilized by the DAL to store retrospectives, notes, tasks, votes, and user data.

d. External Services:
- “External Services” or “Third-Party Integrations” to show APIs such as Tenor for GIF support, relying on external API keys for integration.
- TLS termination logic when using environment variables for TLS keys and certificates.

##### Architectural Patterns and Design Principles
- Separation of concerns: the clear distinction between the presentation layer (Frontend), business logic (Backend controllers, events), data access (DAL), and persistence (Database).
- Mention that the design includes real-time functionality via websockets or event brokers.
- That the modular design in the backend (with directories like controllers, event, socket, dal, and util) supports extensibility and maintainability.
- Containerized deployment options (because of the Dockerfile and docker-compose related instructions) which facilitate consistent deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        F1["Frontend (React, TS, Vite, Tailwind)"]:::frontend
        F2["Real-time Socket (Client)"]:::frontend
    end

    subgraph "Backend Layer"
        B1["API Server (Go)"]:::backend
        B2["Controllers (Auth,Tasks,Retros,etc.)"]:::backend
        B3["Data Access Layer (DAL)"]:::backend
        B4["Event System (Real-time Updates)"]:::backend
        B5["Session Management"]:::backend
        B6["Socket Management"]:::backend
        B7["GIF Integration (Tenor)"]:::backend
    end

    D["SQL Database"]:::db
    E["External Services (Tenor API)"]:::external

    %% Connections
    F1 -->|"REST_API"| B1
    F2 <-->|"WebSocket"| B4

    B1 --> B2
    B1 --> B3
    B1 --> B4
    B1 --> B5
    B1 --> B6
    B1 --> B7

    B2 -->|"calls"| B3
    B3 -->|"reads/writes"| D
    B7 -->|"calls"| E

    %% Click Events
    click F1 "https://github.com/ellgreen/thoughts/tree/main/ui/"
    click F2 "https://github.com/ellgreen/thoughts/blob/main/ui/src/lib/socket.ts"
    click B1 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/"
    click B2 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/controllers/"
    click B3 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/dal/"
    click B4 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/event/"
    click B5 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/session/"
    click B6 "https://github.com/ellgreen/thoughts/tree/main/cmd/thoughts/socket/"
    click B7 "https://github.com/ellgreen/thoughts/blob/main/cmd/thoughts/gif/tenor.go"
    click D "https://github.com/ellgreen/thoughts/tree/main/migrations/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef db fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
