Getting Started¶

Welcome to the QuoinAPI project! This guide will help you set up your development environment and get the application running locally.

Prerequisites¶

Ensure you have the following tools installed:

• Git: Version control system.
• Python 3.12+: The programming language used.
• uv: A fast Python package installer and manager.
• just: A handy command runner for project tasks.
• Docker: Required for running the database and services.

Quick Start¶

Follow these steps to get up and running in minutes.

# 1. Clone the Repository
git clone https://github.com/balakmran/quoin-api.git
cd quoin-api

# 2. Configure Environment
cp .env.example .env

# 3. Setup Project (installs deps & git hooks)
just setup

# 4. Start DB, Apply Migrations, and Run the Server
just dev

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

• API Documentation: http://localhost:8000/docs
• Redoc: http://localhost:8000/redoc

Application Home Page¶

When you visit http://localhost:8000, you'll see the application's home page:

This confirms the application is running correctly. The page includes:

• Application name, version, and description
• Quick links to API documentation (Swagger UI and ReDoc)
• Health check endpoint status

Project Structure¶

Understanding the project layout will help you navigate the codebase.

.
├── app/
│   ├── core/                   # Core configuration (settings, logging, exceptions)
│   ├── db/                     # Database session and base models
│   ├── modules/                # Domain-specific feature modules (e.g., user)
│   │   └── user/               # Example module
│   │       ├── exceptions.py   # Domain-specific exceptions
│   │       ├── models.py       # database tables
│   │       ├── schemas.py      # Pydantic models
│   │       ├── repository.py   # CRUD operations
│   │       ├── routes.py       # API endpoints
│   │       └── service.py      # Business logic
│   └── main.py                 # Application entry point
├── tests/                      # Test suite
├── alembic/                    # Database migrations
├── docker-compose.yml          # Local development services
├── justfile                    # Task runner configuration
└── pyproject.toml              # Project dependencies and tool config

What's Next?¶

Now that the app is running, here are the logical next steps:

Troubleshooting¶

Port Conflicts¶

If just dev fails, check if port 8000 is already in use.

# check the process
lsof -i :8000

# kill the process
kill -9 $(lsof -ti:8000)

Database Connection¶

If the app cannot connect to the database:

1. Ensure the Docker container is running: docker ps
2. Check logs: docker compose logs db
3. Restart the database: just db