# excali-studio/excali-api architecture

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

- Interactive diagram: https://gitdiagram.com/excali-studio/excali-api
- Repository: https://github.com/excali-studio/excali-api

## Overview

##### Main Components

a) External Services Layer:
- Google OAuth Service (for authentication)
- Frontend Client (Excali-front-wrapper)
- Excalidraw Room Service (for live collaboration)

b) API Gateway Layer:
- NestJS Application (main entry point)
- Swagger Documentation endpoint
- Authentication endpoints
- Session management

c) Core Modules Layer:
- Auth Module
- Google Strategy
- Guards (Authentication, Roles)
- Session Serializer
- Canvas Module
- Canvas Management
- Canvas Access Control
- Canvas Tags
- User Module
- User Management
- Role Management

d) Database Layer:
- PostgreSQL Database with entities:
- User
- UserRole
- Canvas
- CanvasAccess
- CanvasState
- CanvasTag

##### Relationships and Flows

- External client requests → API Gateway
- API Gateway → Auth Module → Google OAuth
- Auth Module → User Module for user management
- Authenticated requests → Canvas Module
- All modules → Database Layer
- Canvas Module → Excalidraw Room Service for live collaboration

##### Architectural Patterns to Highlight

- Module-based architecture (NestJS)
- Guard-based security pattern
- Repository pattern for data access
- Strategy pattern for authentication

##### Technical Details

- NestJS as the main framework
- Passport.js integration
- PostgreSQL database
- Session-based authentication
- REST API endpoints

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services Layer
    subgraph ExternalServices
        Client[Frontend Client]:::external
        GoogleOAuth[Google OAuth Service]:::external
        ExcalidrawRoom[Excalidraw Room Service]:::external
    end

    %% API Gateway Layer
    subgraph APIGateway
        NestApp[NestJS Application]:::gateway
        click NestApp "https://github.com/Excali-Studio/excali-api/blob/main/src/main.ts"
        SwaggerDocs[Swagger Documentation]:::gateway
        click SwaggerDocs "https://github.com/Excali-Studio/excali-api/blob/main/src/helpers/swagger.ts"
    end

    %% Core Modules Layer
    subgraph CoreModules
        %% Auth Module
        subgraph AuthModule
            AuthService[Auth Service]:::auth
            click AuthService "https://github.com/Excali-Studio/excali-api/blob/main/src/auth/auth.service.ts"
            GoogleStrategy[Google Strategy]:::auth
            click GoogleStrategy "https://github.com/Excali-Studio/excali-api/blob/main/src/auth/strategy/google.strategy.ts"
            AuthGuards[Auth Guards]:::auth
            click AuthGuards "https://github.com/Excali-Studio/excali-api/blob/main/src/auth/guard/authenticated.guard.ts"
            SessionSerializer[Session Serializer]:::auth
            click SessionSerializer "https://github.com/Excali-Studio/excali-api/blob/main/src/auth/serializer/session.serializer.ts"
        end

        %% Canvas Module
        subgraph CanvasModule
            CanvasManagement[Canvas Management]:::canvas
            click CanvasManagement "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/canvas.service.ts"
            CanvasAccess[Access Control]:::canvas
            click CanvasAccess "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/guard/canvas.guard.ts"
            CanvasTags[Canvas Tags]:::canvas
            click CanvasTags "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/canvas-tag.service.ts"
        end

        %% User Module
        subgraph UserModule
            UserManagement[User Management]:::user
            click UserManagement "https://github.com/Excali-Studio/excali-api/blob/main/src/user/user.service.ts"
            RoleManagement[Role Management]:::user
            click RoleManagement "https://github.com/Excali-Studio/excali-api/blob/main/src/user/entity/user-role.entity.ts"
        end
    end

    %% Database Layer
    subgraph Database
        PostgreSQL[(PostgreSQL)]:::db
        subgraph Entities
            UserEntity[User]:::entity
            click UserEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/user/entity/user.entity.ts"
            RoleEntity[UserRole]:::entity
            click RoleEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/user/entity/user-role.entity.ts"
            CanvasEntity[Canvas]:::entity
            click CanvasEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/entity/canvas.entity.ts"
            AccessEntity[CanvasAccess]:::entity
            click AccessEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/entity/canvas-access.entity.ts"
            StateEntity[CanvasState]:::entity
            click StateEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/entity/canvas-state.entity.ts"
            TagEntity[CanvasTag]:::entity
            click TagEntity "https://github.com/Excali-Studio/excali-api/blob/main/src/canvas/entity/canvas-tag.entity.ts"
        end
    end

    %% Relationships
    Client --> NestApp
    NestApp --> SwaggerDocs
    NestApp --> AuthService
    AuthService --> GoogleOAuth
    AuthService --> UserManagement
    AuthGuards --> UserManagement
    NestApp --> CanvasManagement
    CanvasManagement --> ExcalidrawRoom
    CanvasManagement --> CanvasAccess
    CanvasManagement --> CanvasTags
    UserManagement --> PostgreSQL
    CanvasManagement --> PostgreSQL
    
    %% Styles
    classDef external fill:#2374ab
    classDef gateway fill:#57a773
    classDef auth fill:#ffc857
    classDef canvas fill:#7dce82
    classDef user fill:#3da35d
    classDef db fill:#95a5a6
    classDef entity fill:#bdc3c7

    %% Legend
    subgraph Legend
        L1[External Services]:::external
        L2[Gateway Components]:::gateway
        L3[Auth Components]:::auth
        L4[Canvas Components]:::canvas
        L5[User Components]:::user
        L6[Database]:::db
        L7[Entities]:::entity
    end
```
