FictionArchive/Documentation/README.md

FictionArchive

A distributed microservices-based web application for managing fiction and novel content. Features include importing from external sources, multi-language translation, file storage, and user management.

Architecture

FictionArchive uses a GraphQL Fusion gateway pattern to orchestrate multiple domain services with event-driven communication via RabbitMQ. More information available in ARCHITECTURE.md

Prerequisites

• .NET SDK 8.0+
• Node.js 20+
• Python 3 (for gateway build script)
• Docker & Docker Compose
• PostgreSQL 16+
• RabbitMQ 3+

Required CLI Tools

# Hot Chocolate Fusion CLI
dotnet tool install -g HotChocolate.Fusion.CommandLine

Getting Started

Local Development

1. Clone the repository

   git clone <repository-url>
   cd FictionArchive
   

2. Start infrastructure (PostgreSQL, RabbitMQ)

   docker compose up -d postgres rabbitmq
   

3. Build and run backend

   dotnet restore
   dotnet build FictionArchive.sln
   
   # Start services (in separate terminals or use a process manager)
   dotnet run --project FictionArchive.Service.NovelService
   dotnet run --project FictionArchive.Service.UserService
   dotnet run --project FictionArchive.Service.TranslationService
   dotnet run --project FictionArchive.Service.FileService
   dotnet run --project FictionArchive.Service.SchedulerService
   dotnet run --project FictionArchive.Service.AuthenticationService
   
   # Start the gateway (builds fusion schema automatically)
   dotnet run --project FictionArchive.API
   

4. Build and run frontend

   cd fictionarchive-web
   npm install
   npm run codegen    # Generate GraphQL types
   npm run dev        # Start dev server at http://localhost:5173
   

Docker Deployment

1. Create environment file

   cp .env.example .env
   # Edit .env with your configuration
   

2. Start all services

   docker compose up -d
   

Configuration

Environment Variables

Create a .env file in the project root:

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password

# RabbitMQ
RABBITMQ_USER=guest
RABBITMQ_PASSWORD=your-secure-password

# External Services
NOVELPIA_USERNAME=your-username
NOVELPIA_PASSWORD=your-password
DEEPL_API_KEY=your-api-key

# S3 Storage
S3_ENDPOINT=https://s3.example.com
S3_BUCKET=fictionarchive
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key

# OIDC Authentication
OIDC_AUTHORITY=https://auth.example.com/application/o/fiction-archive/
OIDC_CLIENT_ID=your-client-id

Frontend Environment

Create fictionarchive-web/.env.local:

VITE_GRAPHQL_URI=http://localhost:5234/graphql/
VITE_OIDC_AUTHORITY=https://auth.example.com/application/o/fiction-archive/
VITE_OIDC_CLIENT_ID=your-client-id
VITE_OIDC_REDIRECT_URI=http://localhost:5173/
VITE_OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:5173/

Building the GraphQL Gateway

The API gateway uses Hot Chocolate Fusion to compose schemas from all subgraphs. The gateway schema is rebuilt automatically when building the API project.

Manual rebuild:

cd FictionArchive.API
python build_gateway.py

Skip specific services by adding them to FictionArchive.API/gateway_skip.txt:

FictionArchive.Service.NovelService.Tests

CI/CD

The project uses Gitea Actions with the following workflows:

Workflow	Trigger	Description
build.yml	Push/PR to master	CI checks - builds and tests
build-subgraphs.yml	Service changes on master	Builds subgraph .fsp packages
build-gateway.yml	Gateway changes or subgraph builds	Composes gateway and builds Docker image
release.yml	Tag v*.*.*	Builds and pushes all Docker images

Release Process

git tag v1.0.0
git push origin v1.0.0

Project Structure

FictionArchive/
├── FictionArchive.sln
├── FictionArchive.Common/              # Shared enums and extensions
├── FictionArchive.Service.Shared/      # Shared infrastructure (EventBus, DB)
├── FictionArchive.API/                 # GraphQL Fusion Gateway
├── FictionArchive.Service.NovelService/
├── FictionArchive.Service.UserService/
├── FictionArchive.Service.TranslationService/
├── FictionArchive.Service.FileService/
├── FictionArchive.Service.SchedulerService/
├── FictionArchive.Service.AuthenticationService/
├── FictionArchive.Service.NovelService.Tests/
├── fictionarchive-web/                 # React frontend
├── docker-compose.yml
└── .gitea/workflows/                   # CI/CD workflows

Testing

# Run all tests
dotnet test FictionArchive.sln

# Run specific test project
dotnet test FictionArchive.Service.NovelService.Tests

Documentation

• ARCHITECTURE.md - Detailed architecture documentation
• AGENTS.md - Development guidelines and coding standards