Project Overview

This service provides CRUD endpoints for GitHub repository metadata. Submitting a GitHub URL triggers a live fetch from the GitHub API; the result is validated, stored in PostgreSQL, and returned to the caller. Subsequent reads are served from the local database without hitting GitHub.

The project is structured as a production-oriented backend service: fully async, layered architecture, typed throughout, and covered by unit and integration tests.

Quick Start

The fastest path to a running service:

# Clone and start (PostgreSQL + migrations + API server — all-in-one)
docker compose up --build

To run the test suite (requires a separate test database — see Testing):

pytest -v

Architecture

The codebase follows a strict three-layer architecture. Layers only communicate downward — routes call services, services call the repository layer and the GitHub client, nothing flows upward.

┌──────────────────────────────────────────────────────┐
│                     HTTP Client                      │
└────────────────────────┬─────────────────────────────┘
                         │  HTTP request
┌────────────────────────▼─────────────────────────────┐
│               API Layer  (app/api/)                  │
│   Route handlers — validate input, delegate to       │
│   service, return typed response. Zero logic here.   │
└────────────────────────┬─────────────────────────────┘
                         │  Domain calls
┌────────────────────────▼─────────────────────────────┐
│            Service Layer  (app/services/)             │
│   Orchestrates use cases: parse URL, fetch GitHub,   │
│   check duplicates, persist, return response schema. │
└──────────────┬──────────────────────┬────────────────┘
               │                      │
┌──────────────▼──────────┐  ┌────────▼────────────────┐
│    Repository Layer      │  │     GitHub Client        │
│  (app/repositories/)     │  │  (app/services/          │
│  Async SQLAlchemy — all  │  │   github_client.py)      │
│  DB access lives here.   │  │  httpx.AsyncClient —     │
│                          │  │  maps HTTP → exceptions. │
└──────────────┬──────────┘  └────────┬────────────────┘
               │                      │
┌──────────────▼──────────┐  ┌────────▼────────────────┐
│       PostgreSQL         │  │    GitHub REST API       │
└─────────────────────────┘  └─────────────────────────┘

Exception flow: domain exceptions (app/core/exceptions.py) propagate from services upward, and are mapped to HTTP status codes exclusively in app/api/exception_handlers.py. No layer below the API layer imports FastAPI or HTTP status codes.

Tech Stack

Project Structure

github-metadata-service/
├── app/
│   ├── api/
│   │   ├── dependencies.py        # Typed Annotated aliases (DBSession, RepoService)
│   │   ├── exception_handlers.py  # Domain exception → HTTP status code mapping
│   │   └── v1/
│   │       └── repositories.py    # Route handlers — thin, no logic
│   ├── core/
│   │   ├── config.py              # pydantic-settings, all env vars
│   │   ├── exceptions.py          # Domain exception hierarchy
│   │   └── logging.py             # structlog configuration
│   ├── db/
│   │   ├── base.py                # SQLAlchemy DeclarativeBase
│   │   └── session.py             # Async engine, session factory, get_db_session
│   ├── models/
│   │   └── repository.py          # Repository ORM model
│   ├── schemas/
│   │   ├── github.py              # GitHub API response schema (internal)
│   │   └── repository.py          # API request/response schemas (public)
│   ├── repositories/
│   │   └── repository_repo.py     # All database access for Repository model
│   ├── services/
│   │   ├── github_client.py       # httpx.AsyncClient wrapper, exception mapping
│   │   └── repository_service.py  # Use-case orchestration
│   └── main.py                    # App factory, lifespan, health endpoints
├── alembic/
│   ├── env.py                     # Async-aware Alembic environment
│   ├── script.py.mako
│   └── versions/
│       └── 20260526_0001_create_repositories_table.py
├── tests/
│   ├── conftest.py                # Shared fixtures: engine, client, mock_github_api
│   ├── unit/
│   │   ├── test_github_url_validation.py
│   │   ├── test_repository_service.py
│   │   └── test_github_client.py
│   └── integration/
│       └── test_repositories_api.py
├── .env.example
├── alembic.ini
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

Prerequisites

• Python 3.11+
• PostgreSQL 15+ (or Docker)
• pip (or uv)

Setup

1. Clone the repository

git clone https://github.com/your-org/github-metadata-service.git
cd github-metadata-service

2. Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install dependencies

# Production dependencies
pip install -e .

# Development dependencies (includes test tools, linter, type checker)
pip install -e ".[dev]"

4. Configure environment variables

cp .env.example .env
# Edit .env — at minimum, set DATABASE_URL and optionally GITHUB_TOKEN

5. Run database migrations

alembic upgrade head

Environment Variables

All variables are read from a .env file in the project root. Copy .env.example to get started.

*Required when running the integration test suite.

DATABASE_URL format:

postgresql+asyncpg://USER:PASSWORD@HOST:PORT/DBNAME

Example:

postgresql+asyncpg://postgres:postgres@localhost:5432/github_metadata

Running Locally

Start PostgreSQL

If you have Docker available:

docker run -d \
  --name github-metadata-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=github_metadata \
  -p 5432:5432 \
  postgres:16-alpine

Apply migrations

alembic upgrade head

Start the server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.
Interactive docs: http://localhost:8000/docs
Alternative docs: http://localhost:8000/redoc

Running with Docker Compose

Docker Compose starts PostgreSQL, waits for the health check to pass, runs migrations, and starts the API server — in a single command.

# Optional: set your GitHub token to avoid rate limits
export GITHUB_TOKEN=ghp_your_token_here

docker compose up --build

The service is available at http://localhost:8000 once the app container logs application_startup.

# Stop and remove containers (data volume is preserved)
docker compose down

# Stop and remove containers AND the database volume
docker compose down -v

Database Migrations

This project uses Alembic for schema migrations. The alembic/env.py is configured for async SQLAlchemy using the run_sync bridge pattern required by asyncpg.

# Apply all pending migrations
alembic upgrade head

# Roll back the most recent migration
alembic downgrade -1

# Roll back all migrations (returns to empty schema)
alembic downgrade base

# Show migration history
alembic history --verbose

# Show current applied revision
alembic current

# Generate a new migration (requires a running DB)
alembic revision --autogenerate -m "add_column_x_to_repositories"

Note: Always review autogenerated migrations before applying. Alembic's autogenerate does not detect all changes (e.g. server defaults, some index changes).

API Reference

Base URL

http://localhost:8000/api/v1

Endpoints

POST /repositories

Submit a GitHub repository URL. Fetches metadata from GitHub and stores it locally.

Request body:

{
  "github_url": "https://github.com/tiangolo/fastapi"
}

Success response — 201 Created:

{
  "id": 1,
  "github_id": 116195547,
  "owner": "tiangolo",
  "repo_name": "fastapi",
  "full_name": "tiangolo/fastapi",
  "description": "FastAPI framework, high performance, easy to learn, fast to code",
  "html_url": "https://github.com/tiangolo/fastapi",
  "stars": 75000,
  "forks": 6100,
  "language": "Python",
  "github_created_at": "2018-12-08T08:21:47Z",
  "github_updated_at": "2024-01-15T10:00:00Z",
  "created_at": "2026-05-26T12:00:00Z",

A scalable AI-ready backend with FastAPI and pgvector — supporting RAG vector memory, async PostgreSQL, and production Docker setup.