How mharfe23/fantasy-writer-ai works
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