Ideological Atlas - Backend API

📖 Description

This repository contains the Backend API for the Ideological Atlas project. It is a robust and scalable application designed to manage users, complex ideological test structures, affinity calculations, and geographic/ideological content management.

The system is built on a modern container-based architecture, utilizing the latest stable versions of its core technologies.

🛠️ Technology Stack

The infrastructure relies on the following main components:

• Language: Python 3.14
• Web Framework: Django 6.0
• API: Django Rest Framework (DRF) 3.16+
• Database: PostgreSQL 18
• Package Manager: uv
• Async & Tasks: Celery 5.6 + RabbitMQ 4
• Storage: MinIO (S3 Compatible)
• Containerization: Docker & Docker Compose

🚀 Installation and Local Deployment

The project is fully containerized to facilitate development. A Makefile is used to orchestrate the most common commands.

Prerequisites

• Docker Engine
• Docker Compose
• Make (Optional, but recommended)

Getting Started

1. Clone the repository:

   git clone https://github.com/Ideological-Atlas/backend.git
   cd backend

2. Build and start the environment: This command creates the network, generates the .env file from the template, builds the images, and starts the containers in the background.

   make build

3. Check status: You can view real-time logs to ensure everything started correctly (Backend, Worker, Beat, Flower, Postgres, MinIO).

   make logs

The backend will be available at http://localhost:3141 (or the port defined in your .env).

⚙️ Project Management (Makefile)

The Makefile is the main interface for interacting with the development environment.

Command	Description
make up	Starts containers (forces recreation).
make down	Stops and removes containers and networks.
make logs	Shows logs for the backend container.
make celery-logs	Shows logs for Celery workers.
make bash	Opens a bash terminal inside the backend container.
make shell	Opens a Django shell (shell_plus) with iPython.
make test	Runs the full test suite with coverage.
make migrations	Creates and applies pending migrations.
make messages	Extracts and compiles translation messages (i18n).
make clean-images	Removes project Docker images.

🧪 Code Quality & Testing

We maintain strict quality standards using pre-commit and several static analysis tools.

Pre-commit

It is recommended to install the hooks locally to avoid CI failures:

uv tool install pre-commit
pre-commit install

Running Tests

To run tests inside the Docker container and generate coverage reports:

make test

The system requires a minimum coverage of 90% to pass CI.

Configured Tools

• Ruff: Fast linter and formatter.
• Black & Isort: Code formatting and import sorting.
• Mypy: Static type checking.
• Bandit & Gitleaks: Security analysis and secret detection.

📂 Project Structure

We follow a structure inspired by DDD (Domain-Driven Design) located in src/apps/.

.
├── docker/                 # Docker configurations
├── src/
│   ├── apps/
│   │   ├── core/           # Users, Auth, Geo, Base utilities
│   │   └── ideology/       # Business logic: Tests, Axes, Affinity Calculation
│   ├── backend/            # Django project configuration (settings, urls)
│   ├── locale/             # Translation files
│   └── tests/              # Unit and integration tests
└── Makefile                # Command orchestration

📚 API Documentation

In the development environment (PRODUCTION=False), interactive documentation is available at:

• Swagger UI: http://localhost:3141/api/schema/swagger-ui/
• ReDoc: http://localhost:3141/api/schema/redoc/

🌍 Internationalization

The project supports multiple languages (Default: Spanish and English). To update translations after modifying the code:

make messages

This will automatically execute makemessages and compilemessages for the es locale.

---

Powered by Django