Constellation Backend

The backend monorepo for the Constellation ecosystem, a personalized suite of applications designed to manage and harmonize various aspects of family life.

This project follows a microservices architecture, where each service is an independent, deployable application built with FastAPI. It emphasizes modern, efficient development practices using tools like uv and ruff.

Project Architecture

This is a Python monorepo managed with uv. It contains two primary top-level directories:

• /services: Holds the individual, standalone microservices. Each service is a complete FastAPI application.
• /packages: Contains shared code (libraries) used by one or more services, promoting the DRY (Don't Repeat Yourself) principle.

constellation-backend/
│
├── .env.example              # Example environment variables file
├── Makefile
├── Procfile
├── .gitignore
├── pyproject.toml            # Project configuration and dependencies
├── README.md                 # This file
│
├── packages/
│   ├── shared_models/        # Shared Pydantic models
│   └── shared_utils/         # Shared utilities (e.g., database connection)
│
└── services/
    ├── auth_service/         # Handles user authentication and identity
    ├── expense_service/      # Handles expense tracking logic
    └── ...                   # Future services

graph TD
    subgraph "constellation-backend (Monorepo)"
        direction TB

        subgraph "services/"
            style services/ fill:#e6f3ff,stroke:#005cb3
            AUTH["fa:fa-server auth_service"]
        end

        subgraph "packages/ (shared codes)"
            style packages/ fill:#e6ffed,stroke:#00642e
            SHARED_UTILS["fa:fa-cogs shared_utils\n (database.py)"]
            SHARED_MODELS["fa:fa-cubes shared_models\n (models.py)"]
        end

        AUTH -->|imports| SHARED_UTILS
        AUTH -->|imports| SHARED_MODELS
    end

    subgraph "External Dependencies"
        DB["fa:fa-database MongoDB 
         constellation_db"]
    end

    AUTH -->|connects to| DB

    style AUTH fill:#fff0e6,stroke:#b35900

Loading

Tech Stack

• Framework: FastAPI
• Database: MongoDB
• Async Driver: Motor
• Package & Env Management: uv
• Linting & Formatting: Ruff
• Authentication: Stateless JWT with Refresh Token Rotation
• CORS: Handled via FastAPI Middleware for secure frontend communication.

Monorepo-Level Development Setup

These instructions are for setting up the entire monorepo environment. For instructions on running a specific service, please see the README.md file within that service's directory.

Prerequisites

• Python (3.12 or higher) & pipx
• uv (pipx install uv)
• A running MongoDB instance.

Installation & Setup

1. Clone the repository:

   git clone [https://github.com/YenChengLai/constellation-backend.git](https://github.com/YenChengLai/constellation-backend.git)
   cd constellation-backend

2. Create and activate the virtual environment:

   make install
   source .venv/bin/activate  # For macOS / Linux
   # .venv\Scripts\Activate.ps1 # For Windows PowerShell

3. Setup Environment Variables: Create your local .env file from the template.

   make setup-env

4. Seed the Database: Run the data seeding script to populate the database with initial data (like default categories).

   make db-seed

Running the System

• To run all services concurrently: make run
• To see all available commands: make help

Available Services

Below is a list of the services available in this monorepo. Click the link for detailed information on each service's configuration, API, and how to run it.

• Auth Service: Handles user authentication, identity, and session management.
• (More services will be added here)

Unit Testing

This project uses pytest for unit testing. Tests are located in the /tests directory, mirroring the /services structure.

To run all tests:

pytest