# marvinhill/storytellr architecture

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

- Interactive diagram: https://gitdiagram.com/marvinhill/storytellr
- Repository: https://github.com/marvinhill/storytellr

## Overview

##### Main Components

a. Frontend Layer (Angular Web Application):
- Sub-components:
- User Interface Components (book-detail, editor, library, etc.)
- Services Layer (book.service, chapter.service, etc.)
- Authentication Integration

b. Authentication Layer (Keycloak):
- Include:
- User Management
- OAuth2/OpenID Connect
- Custom Theme (Keywind)

c. Backend Layer (Spring Boot API):
- Sub-components:
- Controllers (REST endpoints)
- Services Layer
- Repository Layer
- Security Configuration

d. Data Storage Layer:
- Main Database (for books, chapters, etc.)
- Keycloak Database
- Public Data Storage (for covers and media)

e. Infrastructure Layer:
- Nginx Proxy
- Docker Containers
- Public Data Server

##### Connection Flows

- User → Nginx Proxy
- Nginx Proxy → Angular Frontend
- Angular Frontend ↔ Keycloak (authentication flow)
- Angular Frontend ↔ Spring Boot API (protected endpoints)
- Spring Boot API ↔ Databases
- Spring Boot API ↔ Keycloak (token validation)

##### Additional Details

Annotations for:
- Security boundaries
- API endpoints grouping (v1)
- Data flow directions
- Authentication flows
- Docker container boundaries

##### Component Details

- Technologies used (Angular, Spring Boot, Keycloak)
- Key features (e.g., Editor.js integration, polling system)
- Communication protocols (REST, OAuth2)

##### Infrastructure Notes

Notes regarding:
- Docker composition
- Development vs Production profiles
- Environment configurations
- Proxy settings

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Layer"
        User((User))
    end

    subgraph "Infrastructure Layer"
        Nginx["Nginx Proxy"]:::infra
        click Nginx "https://github.com/MarvinHill/storytellr/blob/main/proxy/nginx.conf"
        Docker["Docker Containers"]:::infra
        click Docker "https://github.com/MarvinHill/storytellr/blob/main/infra/docker-compose.yml"
        PublicData["Public Data Server"]:::infra
        click PublicData "https://github.com/MarvinHill/storytellr/tree/main/publicdata/"
    end

    subgraph "Frontend Layer"
        Angular["Angular Web Application"]:::frontend
        click Angular "https://github.com/MarvinHill/storytellr/tree/main/webapp/storyteller/src/app/"
        
        subgraph "Angular Components"
            UIComponents["UI Components"]:::frontend
            click UIComponents "https://github.com/MarvinHill/storytellr/tree/main/webapp/storyteller/src/app/components/"
            Services["Services Layer"]:::frontend
            click Services "https://github.com/MarvinHill/storytellr/tree/main/webapp/storyteller/src/app/service/"
            Models["Models"]:::frontend
            click Models "https://github.com/MarvinHill/storytellr/tree/main/webapp/storyteller/src/app/model/"
            AuthGuard["Authentication Guard"]:::frontend
            click AuthGuard "https://github.com/MarvinHill/storytellr/blob/main/webapp/storyteller/src/app/guard/auth.guard.ts"
        end
    end

    subgraph "Authentication Layer"
        Keycloak["Keycloak Authentication"]:::auth
        click Keycloak "https://github.com/MarvinHill/storytellr/blob/main/keycloak/import/storyteller.json"
        KeycloakTheme["Custom Theme (Keywind)"]:::auth
        click KeycloakTheme "https://github.com/MarvinHill/storytellr/tree/main/keycloak/theme/keywind/"
        ThemeProvider["Custom Theme Provider"]:::auth
        click ThemeProvider "https://github.com/MarvinHill/storytellr/blob/main/keycloak/providers/keywind.jar"
    end

    subgraph "Backend Layer"
        SpringBoot["Spring Boot API"]:::backend
        click SpringBoot "https://github.com/MarvinHill/storytellr/blob/main/api/src/main/java/de/storyteller/api/ApiApplication.java"
        
        subgraph "API Components"
            Controllers["REST Controllers"]:::backend
            click Controllers "https://github.com/MarvinHill/storytellr/tree/main/api/src/main/java/de/storyteller/api/v1/controller/"
            BackendServices["Services Layer"]:::backend
            click BackendServices "https://github.com/MarvinHill/storytellr/tree/main/api/src/main/java/de/storyteller/api/service/"
            Repositories["Repository Layer"]:::backend
            click Repositories "https://github.com/MarvinHill/storytellr/tree/main/api/src/main/java/de/storyteller/api/repository/"
            SecurityConfig["Security Configuration"]:::backend
            click SecurityConfig "https://github.com/MarvinHill/storytellr/blob/main/api/src/main/java/de/storyteller/api/SecurityConfig.java"
            AuthServices["Authentication Services"]:::backend
            click AuthServices "https://github.com/MarvinHill/storytellr/tree/main/api/src/main/java/de/storyteller/api/service/auth/"
        end
    end

    subgraph "Data Storage Layer"
        MainDB[(Main Database)]:::database
        KeycloakDB[(Keycloak Database)]:::database
        PublicStorage[(Public Data Storage)]:::database
        click PublicStorage "https://github.com/MarvinHill/storytellr/tree/main/publicdata/"
        DefaultCovers["Default Covers"]:::database
        click DefaultCovers "https://github.com/MarvinHill/storytellr/tree/main/publicdata/default_cover/"
    end

    %% Connections
    User --> Nginx
    Nginx --> Angular
    Angular <--> Keycloak
    Angular <--> SpringBoot
    SpringBoot <--> MainDB
    SpringBoot <--> PublicStorage
    Keycloak <--> KeycloakDB
    SpringBoot <--> Keycloak
    
    %% Internal Component Connections
    Angular --- UIComponents
    Angular --- Services
    Angular --- Models
    Angular --- AuthGuard
    
    Keycloak --- KeycloakTheme
    Keycloak --- ThemeProvider
    
    SpringBoot --- Controllers
    SpringBoot --- BackendServices
    SpringBoot --- Repositories
    SpringBoot --- SecurityConfig
    SpringBoot --- AuthServices
    
    PublicStorage --- DefaultCovers

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef auth fill:#f1c40f,stroke:#f39c12,color:black
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
```
