Arquitetos Backend — Paranormal Order API

RESTful API for managing characters, teams, missions, and NPCs in a Paranormal Order tabletop RPG system.

---

Table of Contents

• Overview
• Key Features
• Tech Stack
• Requirements
• Setup
  • Running with Docker (recommended)
  • Running locally
• Environment Variables
• API Documentation
• Project Structure
• Running Tests
• Authors

---

Overview

Arquitetos Backend is a scalable REST API built with FastAPI and MongoDB designed to power the backend of a Paranormal Order RPG management platform. It handles authentication, role-based access control, character creation, investigator team coordination, mission lifecycle management, ally relationships, and points of interest on the campaign map.

---

Key Features

• JWT Authentication — Secure token-based authentication with role-based access control (GM / Player)
• Character Management — Full CRUD for player characters, including team assignment
• Team Management — Create and manage investigator teams with member control
• Case System — Complete case lifecycle: available → in progress → completed/failed/suspended
• Ally System — Manage NPCs (allies) with per-character relationship tracking (heart system)
• Points of Interest — Create and manage map locations tied to campaigns
• Admin Panel — User management and audit log access for administrators
• Audit Logging — Automatic request/response logging via middleware
• Data Validation — Strict input validation with Pydantic v2
• Containerized — Ready to run with Docker and Docker Compose

---

Tech Stack

Layer	Technology
Framework	FastAPI 0.120
Language	Python 3.12
Database	MongoDB (via PyMongo 4.13)
Validation	Pydantic v2
Auth	JWT (python-jose) + bcrypt
Testing	pytest + mongomock + factory-boy
Linting	Flake8 + Black
Container	Docker + Docker Compose

---

Requirements

• Python >= 3.12
• Docker and Docker Compose (for containerized setup)
• Poetry (for local setup without Docker)

---

Setup

Running with Docker (recommended)

1. Clone the repository

git clone https://github.com/vinicOio222/arquitetos-backend-py
cd arquitetos-backend-py

2. Create the environment file

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

3. Build and start the containers

docker-compose up --build

The API will be available at http://localhost:8000.

---

Running locally

1. Clone the repository

git clone https://github.com/vinicOio222/arquitetos-backend-py
cd arquitetos-backend-py

2. Install Poetry (if not already installed)

pip install poetry

3. Install dependencies

poetry install

4. Activate the virtual environment

poetry shell

5. Create the environment file

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

6. Start the application

uvicorn app.main:app --reload

The API will be available at http://localhost:8000.

---

Environment Variables

Create a .env file in the root directory based on .env.example. Key variables:

Variable	Description	Example
APP_NAME	Application name	Arquitetos Backend
APP_VERSION	Application version	0.1.0
API_PREFIX	Base path for all routes	/api/v1
DEBUG	Enable debug mode	false
DATABASE_URI	MongoDB connection string	mongodb://localhost:27017
DATABASE_NAME	MongoDB database name	arquitetos
SECRET_KEY	JWT signing secret	your-secret-key
ALGORITHM	JWT algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Token expiration in minutes	60
ADMIN_EMAIL	Seed admin user email	admin@example.com
ADMIN_PASSWORD	Seed admin user password	strongpassword

---

API Documentation

After starting the application, interactive API docs are available at:

Interface	URL
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc

---

Project Structure

arquitetos-backend-py/
├── app/
│   ├── main.py                  # Application entrypoint and startup
│   ├── core/
│   │   ├── auth.py              # JWT token validation and dependencies
│   │   ├── config.py            # Settings loaded from environment
│   │   ├── database.py          # MongoDB connection and base model
│   │   ├── exceptions.py        # Custom exception hierarchy (AppError)
│   │   ├── middlewares.py       # Audit logging middleware
│   │   └── security.py          # Password hashing utilities
│   ├── models/
│   │   ├── ally.py              # Ally and Relationship models
│   │   ├── audit_log.py         # Audit log model
│   │   ├── case.py              # Case model and status enum
│   │   ├── character.py         # Character model
│   │   ├── mission.py           # Mission model
│   │   ├── point_of_interest.py # POI model with map location
│   │   ├── team.py              # Team model
│   │   └── user.py              # User model and role enum
│   ├── repositories/
│   │   ├── base_repository.py   # Generic CRUD repository
│   │   ├── ally_repository.py
│   │   ├── case_repository.py
│   │   ├── character_repository.py
│   │   ├── log_repository.py
│   │   ├── point_of_interest_repository.py
│   │   ├── team_repository.py
│   │   └── user_repository.py
│   ├── services/
│   │   ├── base_service.py      # Generic service with exists/raise helpers
│   │   ├── ally_service.py
│   │   ├── case_service.py
│   │   ├── character_service.py
│   │   ├── log_service.py
│   │   ├── point_of_interest_service.py
│   │   ├── team_service.py
│   │   └── user_service.py
│   ├── routers/
│   │   ├── api_router.py        # Root router aggregating all v1 routes
│   │   └── v1/
│   │       ├── admins.py
│   │       ├── allies.py
│   │       ├── auth.py
│   │       ├── cases.py
│   │       ├── characters.py
│   │       ├── points_of_interest.py
│   │       ├── teams.py
│   │       └── users.py
│   ├── schemas/                 # Pydantic request/response schemas
│   └── utils/
│       ├── admin.py             # Admin seeding on startup
│       └── factories.py         # factory-boy factories for testing
├── tests/
│   ├── conftest.py              # Shared fixtures (client, mock_mongo, users)
│   ├── mocks.py                 # MongoMock client wrapper
│   ├── helpers/                 # Per-domain DB insert helpers for tests
│   ├── admin/
│   ├── allies/
│   ├── auth/
│   ├── cases/
│   ├── characters/
│   ├── points_of_interest/
│   └── teams/
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml               # Dependencies and tool config (Poetry)
├── pytest.ini                   # Test configuration and markers
└── wait-for-db.sh               # Docker entrypoint DB readiness probe

---

Running Tests

The test suite uses pytest, mongomock (in-memory MongoDB), and factory-boy for fixtures.

Run all tests:

pytest

Run with coverage report:

pytest --cov=app --cov-report=html
# Open htmlcov/index.html to view the report

Run a specific module:

pytest tests/cases/

---

This a personal project developed with love and dedication to create a robust backend for the Paranormal Order RPG management platform. It is not affiliated with any company or organization, and is intended for educational and hobby purposes.

Authors

• Vinícius dos Santos