# mharfe23/fantasy-writer-ai architecture

> Architecture diagram of the GitHub repository mharfe23/fantasy-writer-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mharfe23/fantasy-writer-ai
- Repository: https://github.com/mharfe23/fantasy-writer-ai

## Overview

##### Project Type & Purpose
- This is a full-stack, microservices-based web platform (“Fantasy Writer AI”) for fantasy authors.
- It offers a React/TypeScript frontend, a Spring Boot “CoreService” backend, a Python TTS “audio-service,” plus scraping utilities.
- It integrates AI (text summaries, image generation, text-to-speech), user management, storage services, and payment/token logic.

##### File-Structure & Architectural Patterns
- Top-level microservices:
- Frontend/ – React + Vite + Tailwind UI client
- backend/CoreService/ – Spring Boot REST API (business logic, security, data access)
- audio-service/ – Python-based TTS microservice
- Scraping/ – standalone scripts for data collection
- Data layers:
- PostgreSQL (users, auth, payments)
- MongoDB (books, chapters, pages, image prompts)
- MinIO (object storage for audio & images)
- External AI services: image-generation API, summarization engine

##### Key Components
a. Frontend Application
- UI components (React pages, forms, dashboards)
- State management via hooks/context
- HTTP/REST calls to CoreService API
b. CoreService (Spring Boot)
- Controllers (AuthController, BookController, etc.)
- Services & Mappers (business rules, DTO mapping)
- Repositories (JPA for PostgreSQL, MongoTemplate for MongoDB)
- Security layer (JWT filter, WebConfig)
c. Audio-service (Python)
- Flask/FastAPI endpoint(s) for TTS
- Local voice model files
d. Scraping Utility
- Python scripts for offline data extraction
e. Datastores & Storage
- PostgreSQL instance
- MongoDB instance
- MinIO (S3-compatible object store)
f. External AI & Payment Systems
- Image-generation API (e.g., Stable Diffusion service)
- Payment gateway (e.g., Stripe)

##### Relationships & Data Flows
- Frontend → CoreService:
- Auth requests (login, signup)
- CRUD operations for books/chapters/pages
- AI feature requests (summary, image, audio)
- CoreService → Databases:
- PostgreSQL for user/auth/payment data
- MongoDB for content storage
- CoreService → audio-service: REST call for TTS, then stores output in MinIO
- CoreService → External AI API: POST prompts for image generation
- Frontend ← MinIO: fetch audio and image assets via presigned URLs
- CoreService logs usage (TokenUsageLog)

##### Architectural Patterns & Design Principles
- Microservices: independent deployable units (Spring Boot, Python service)
- Layered architecture (controllers → services → repositories)
- DTO/mapper pattern for decoupling entity and API models
- JWT-based stateless authentication
- Eventual consistency: separate data stores for different domains
- Externalized configuration via application.yml and environment variables

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        FrontendApp["Frontend Application"]:::frontend
        UIComp["UI Components"]:::frontend
        StateMgmt["State Management & Hooks"]:::frontend
        HTTPServices["HTTP/REST Services"]:::frontend
    end

    %% CoreService Layer
    subgraph "CoreService (Spring Boot)" 
        direction TB
        CoreServiceApp["CoreService Application"]:::core

        subgraph "Controllers"
            Controllers["Controllers"]:::core
        end

        subgraph "Services & Mappers"
            ServicesBL["Business Logic Services"]:::core
            DTOsMappers["DTOs & Mappers"]:::core
        end

        subgraph "Repositories"
            Repositories["Repositories (JPA, MongoTemplate)"]:::core
        end

        subgraph "Security & Config"
            Security["Security Layer (JWT, Filters)"]:::core
            Config["Configuration (CORS, application.yml)"]:::core
        end

        subgraph "Models"
            Models["Entity Models"]:::core
        end
    end

    %% Audio-service Layer
    subgraph "Audio-service (TTS Microservice)"
        direction TB
        AudioService["Audio-service"]:::audio
        Endpoints["TTS Endpoints"]:::audio
        Voices["Voice Model Files"]:::audio
        Requirements["Requirements"]:::audio
    end

    %% Scraping Utility
    Scraping["Scraping Utility"]:::ext

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        PostgreSQL["PostgreSQL"]:::db
        MongoDB["MongoDB"]:::db
        MinIO["MinIO (S3 Storage)"]:::db
    end

    %% External Services
    subgraph "External AI & Payment Services"
        direction TB
        ImageAPI["Image Generation API"]:::ext
        Summarization["Summarization Engine"]:::ext
        Payment["Payment Gateway"]:::ext
    end

    %% Orchestration
    Orchestration["Docker Compose Orchestration"]:::infra

    %% Relationships
    FrontendApp --> UIComp
    FrontendApp --> StateMgmt
    FrontendApp --> HTTPServices
    FrontendApp -->|"HTTP/REST"| CoreServiceApp
    FrontendApp -->|"Fetch assets via presigned URLs"| MinIO

    CoreServiceApp --> Controllers
    CoreServiceApp --> ServicesBL
    CoreServiceApp --> DTOsMappers
    CoreServiceApp --> Repositories
    CoreServiceApp --> Security
    CoreServiceApp --> Config
    CoreServiceApp --> Models

    CoreServiceApp -->|"JPA/PostgreSQL"| PostgreSQL
    CoreServiceApp -->|"MongoTemplate"| MongoDB
    CoreServiceApp -->|"S3 API"| MinIO
    CoreServiceApp -->|"HTTP/REST"| AudioService
    CoreServiceApp -->|"POST prompts"| ImageAPI
    CoreServiceApp -->|"Log token usage"| PostgreSQL

    AudioService --> Endpoints
    AudioService --> Voices
    AudioService --> Requirements
    AudioService -->|"Store audio via S3 API"| MinIO

    Orchestration --> FrontendApp
    Orchestration --> CoreServiceApp
    Orchestration --> AudioService

    Scraping -->|"Offline data extraction"| MongoDB

    %% Click Events
    click FrontendApp "https://github.com/mharfe23/fantasy-writer-ai/tree/main/Frontend/"
    click UIComp "https://github.com/mharfe23/fantasy-writer-ai/tree/main/Frontend/src/components/"
    click StateMgmt "https://github.com/mharfe23/fantasy-writer-ai/tree/main/Frontend/src/hooks/"
    click HTTPServices "https://github.com/mharfe23/fantasy-writer-ai/tree/main/Frontend/src/services/"
    click CoreServiceApp "https://github.com/mharfe23/fantasy-writer-ai/blob/main/backend/CoreService/src/main/java/com/mharfe/coreService/CoreServiceApplication.java"
    click Controllers "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/controller/"
    click ServicesBL "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/service/"
    click Repositories "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/repository/"
    click Security "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/security/"
    click Config "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/config/"
    click DTOsMappers "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/dto/"
    click DTOsMappers "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/mapper/"
    click Models "https://github.com/mharfe23/fantasy-writer-ai/tree/main/backend/CoreService/src/main/java/com/mharfe/coreService/model/"
    click Config "https://github.com/mharfe23/fantasy-writer-ai/blob/main/backend/CoreService/src/main/resources/application.yml"
    click Endpoints "https://github.com/mharfe23/fantasy-writer-ai/blob/main/audio-service/audio_service.py"
    click Voices "https://github.com/mharfe23/fantasy-writer-ai/tree/main/audio-service/voices/"
    click Requirements "https://github.com/mharfe23/fantasy-writer-ai/blob/main/audio-service/requirements.txt"
    click Scraping "https://github.com/mharfe23/fantasy-writer-ai/blob/main/Scraping/extract_images.py"
    click Orchestration "https://github.com/mharfe23/fantasy-writer-ai/blob/main/backend/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef audio fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#F0E68C,stroke:#333,stroke-width:1px
```
