Skip to content

About

An educational project demonstrating how to build a backend web server with Python. While designed for learning, its architecture — authentication, authorization, rate limiting, and consistent error handling — provides a solid foundation for real-world projects.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Backend Core

An educational project demonstrating how to build a backend web server with Python. While designed for learning, its architecture — authentication, authorization, rate limiting, and consistent error handling — provides a solid foundation for real-world projects.

License: Apache-2.0 License: CC0-1.0

Project Structure

backend-core/
├── packages/           # Monorepo root containing all independently deployable
│   │                   # Python modules and shared libraries. Each package
│   │                   # strictly follows the standard `src/` layout (e.g.
│   │                   # `packages/server/src/server/`) for clean imports and
│   │                   # packaging.
│   │
│   ├── server/         # FastAPI application handling HTTP routing, request
│   │                   # validation, authentication, authorization, rate
│   │                   # limiting, access logging, and global error handling.
│   │
│   ├── shared/         # Cross-process shared infrastructure. Contains base
│   │                   # configurations and unified client abstractions for
│   │                   # external services.
│   │
│   ├── services/       # Cross-process business logic built on top of shared
│   │                   # infrastructure. Contains self-contained service
│   │                   # modules that implement domain-specific behaviour.
│   │
│   └── scripts/        # Standalone automation scripts for environment
│                       # bootstrapping, infrastructure initialization, and
│                       # auxiliary utility tasks.
│
├── migrations/         # Alembic migration environment and database schema
│                       # change scripts.
│
├── docs/               # Technical documentation covering project dependencies,
│                       # codebase layout, and request flow diagrams for every
│                       # endpoint.
│
├── LICENSES/           # Full texts of all licenses used in the project.
│
├── LICENSE.txt         # Licensing overview: which license applies to which files.
│
├── docker-compose.yml  # Docker Compose stack for running infrastructure
│                       # services (PostgreSQL, Redis) locally.
│
├── .env.example        # Environment variable template. Copied to .env during
│                       # bootstrapping with auto-generated credentials for
│                       # credential fields.
│
├── pixi.toml           # Pixi configuration defining a single shared
│                       # development environment.
│
├── pixi.lock           # Fully resolved and reproducible dependency lockfile.
│
└── justfile            # Task runner: bootstrap commands, database migration
                        # targets, runtime process launchers, and Docker Compose
                        # shortcuts.

Quick Start

I. Prerequisites

Component Requirement
Operating System GNU/Linux-based system
Architecture x86_64
Package Manager Pixi
Container Tools Docker and Docker Compose

Note:
These are not strict requirements, but rather the baseline environment where the code is guaranteed to run out of the box. Alternative setups are possible but may require manual configuration.

II. Setup

  1. Clone the repository

    git clone https://github.com/snegoviol/backend-core.git
    cd backend-core
  2. Install dependencies

    pixi install
  3. Activate environment

    pixi shell

III. Launch

Once the environment is activated, the service can be launched with a single command:

just quick-start

The launch script will automatically execute all necessary setup steps, start the server, and open the Swagger UI in your default web browser once the API is ready.

Want to see what happens under the hood?
The launch script is fully documented with step-by-step comments explaining each action. You can find it here:

IV. Cleanup

When you are done, shut down the running services by terminating the server terminal process, then bring down the infrastructure containers:

just docker-down

License

Each file in this repository is licensed under one of the following licenses:

The applicable license is stated in the header comment of each file. See LICENSE.txt for details.

About

An educational project demonstrating how to build a backend web server with Python. While designed for learning, its architecture — authentication, authorization, rate limiting, and consistent error handling — provides a solid foundation for real-world projects.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages