Genie Backend API

Genie Backend API is a FastAPI service for AI-assisted recommendations, chat, location-aware discovery, notifications, invitations, friends, and shared content workflows. It combines async SQLAlchemy, Alembic migrations, Redis/RabbitMQ-backed background processing, WebSocket messaging, and integrations with LLM and search providers.

This repository demonstrates backend engineering across API design, async data access, service-layer organization, background tasks, external integrations, cloud secret boundaries, and deployment-ready configuration.

Key Features

• FastAPI application with modular routers for users, chat, recommendations, search, notifications, location, invitations, sharing, and WebSockets.
• Async SQLAlchemy database access with Alembic migrations.
• Recommendation workflows backed by LLM/search providers such as OpenAI, Groq, Google GenAI, Tavily, Exa, TripAdvisor, and related APIs.
• Private chat and LLM chat session/message models.
• WebSocket endpoint structure for real-time communication.
• Celery task app for recommendation background jobs.
• Redis result backend and RabbitMQ broker support.
• Firebase Admin integration for identity/device workflows.
• AWS Secrets Manager helper for production secret retrieval.
• Dockerfile and Compose stack for API, PostgreSQL, RabbitMQ, and Redis.

Tech Stack

• Python 3.9+
• FastAPI
• SQLAlchemy async ORM
• Alembic
• PostgreSQL / PostGIS-compatible models
• Redis
• RabbitMQ
• Celery
• Pydantic settings
• Firebase Admin
• OpenAI, Groq-compatible APIs, Google GenAI, Tavily, Exa, Mem0
• Docker and Docker Compose

Architecture Overview

The application is organized around FastAPI routers, service modules, SQLAlchemy models, and schema objects:

• app/main.py wires the router modules into the FastAPI app.
• app/routers/ contains HTTP and WebSocket endpoint modules.
• app/services/ contains business logic for chat, friends, invitations, notifications, recommendations, shared content, similarity, and users.
• app/models/ contains SQLAlchemy models.
• app/schemas/ contains request/response schemas.
• app/tasks/ contains Celery task configuration and recommendation task helpers.
• alembic/ contains database migration configuration and migration versions.
• app/secrets_manager.py centralizes AWS Secrets Manager access for production secrets.

See docs/architecture.md.

Screenshots And Demo

This is an API backend. Public demos should use API docs and sanitized example requests instead of production data.

Local docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Local Setup

Prerequisites

• Python 3.9+
• uv
• Docker and Docker Compose

Configure Environment

cp .env.example .env

Fill in placeholder values for the providers you want to exercise. For routes that call external services, real API keys are required. For syntax checks and local database work, placeholder values are enough.

Install Dependencies

uv sync --dev

Run Dependencies With Docker

docker compose up -d db rabbitmq redis

Apply Migrations

uv run alembic upgrade head

Start The API

uv run uvicorn app.main:app --reload

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

Docker Usage

Run the full local stack:

cp .env.example .env
docker compose up --build

This starts:

• FastAPI app on localhost:8000
• PostgreSQL on localhost:5432
• RabbitMQ on localhost:5672
• RabbitMQ management UI on localhost:15672
• Redis on localhost:6379

Environment Variables

Important variables:

Variable	Purpose
ENVIRONMENT	development or production
HOST	PostgreSQL host
PORT	PostgreSQL port
DATABASE	PostgreSQL database name
DB_USERNAME	PostgreSQL username
DB_PASSWORD	PostgreSQL password
RABBITMQ_URL	Celery broker URL
REDIS_URL	Celery result backend / Redis URL
OPENAI_API_KEY	OpenAI API key
GROQ_API_KEY	Groq-compatible API key
GOOGLE_API_KEY	Google GenAI API key
TAVILY_API_KEY	Tavily search API key
EXA_API_KEY	Exa search API key
MEM0_API_KEY	Mem0 memory API key
JWT_API_KEY	JWT signing key used by protected routes
DATABASE_SECRETS_NAME	AWS Secrets Manager database secret name for production

See .env.example.

Testing And Verification

The current repository includes a recommendation test script and can run syntax-level checks without external services:

python -m compileall app alembic

For API-level testing, configure .env, start dependencies, run migrations, and then add focused FastAPI tests around the routes being changed.

API Documentation

FastAPI provides:

• Swagger UI: /docs
• ReDoc: /redoc

Main route groups:

• users and invitations
• friends and user blocks/reports
• recommendations
• chat and private chat messages
• LLM sessions
• device tokens and notifications
• location
• sharing
• search
• Google Places and TripAdvisor integrations
• WebSocket messaging
• database/internal utility endpoints

See docs/api.md.

Deployment Notes

Production should use managed PostgreSQL, Redis/RabbitMQ or equivalent broker infrastructure, a secrets manager, and explicit environment values. Do not rely on local placeholder credentials.

See docs/deployment.md.

What This Project Demonstrates

• Building a modular FastAPI backend with async SQLAlchemy.
• Managing schema evolution through Alembic migrations.
• Integrating multiple LLM/search/location providers behind service modules.
• Designing background processing with Celery.
• Handling production secret retrieval through AWS Secrets Manager.
• Structuring an API around routers, services, schemas, and models.

Future Improvements

• Add a dedicated pytest suite for routers and services.
• Add contract tests for provider adapters with mocked external clients.
• Add health endpoints for database, Redis, RabbitMQ, and external provider readiness.
• Add structured logging and request correlation IDs.
• Expand Docker Compose with separate Celery worker service.

Security

Do not commit .env, real cloud credential config files, API keys, Firebase credentials, JWT signing keys, server PEM files, database dumps, or production logs. Use clientLibraryConfig-aws-provider.example.json as a placeholder template only.

See SECURITY.md.