# 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](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**
```bash
# Hot Chocolate Fusion CLI
dotnet tool install -g HotChocolate.Fusion.CommandLine
```

## Getting Started

### Local Development

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd FictionArchive
   ```

2. **Start infrastructure** (PostgreSQL, RabbitMQ)
   ```bash
   docker compose up -d postgres rabbitmq
   ```

3. **Build and run backend**
   ```bash
   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**
   ```bash
   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**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

2. **Start all services**
   ```bash
   docker compose up -d
   ```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```bash
# 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`:

```bash
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:**
```bash
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

```bash
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

```bash
# Run all tests
dotnet test FictionArchive.sln

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

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) - Detailed architecture documentation
- [AGENTS.md](AGENTS.md) - Development guidelines and coding standards