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

Clone the repository

git clone <repository-url>
cd FictionArchive

Start infrastructure (PostgreSQL, RabbitMQ)
```
docker compose up -d postgres rabbitmq
```

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

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

Create environment file

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

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