AIRIS Microservices Platform

A comprehensive microservices platform built with FastAPI, featuring authentication, file storage, monitoring, and API gateway services.

Quickstart: Service Startup Order

To ensure reliable startup and health of all services, follow this recommended order when bringing up the AIRIS stack with Docker Compose v2:

1. Core Infrastructure

Start the database, cache, and monitoring stack:

make up-core

Check: Wait for all to be healthy using make ps and logs.

2. Core Microservices

Start the main backend services (after DB/cache are healthy):

make up-micro

Check: Each service should respond to /health (e.g., curl http://localhost:8008/health for chat, curl http://localhost:8001/health for auth, curl http://localhost:8007/health for MCP).

3. Monitoring Service

Start the monitoring service (after Prometheus, Grafana, Alertmanager are up):

make up-monitoring

Check: curl http://localhost:8003/health

4. API Gateway

Start the API Gateway (after all other services are healthy):

make up-gateway

Check: curl http://localhost:8000/health

Tip: After each step, use make logs SERVICE=service-name and health endpoints to verify readiness before proceeding.

Makefile Shortcuts

The included Makefile provides convenient shortcuts for common operations:

Command	Description
`make up-core`	Start core infrastructure (DB, cache, monitoring stack)
`make up-micro`	Start core microservices (auth, storage, chat, mcp, rag)
`make up-monitoring`	Start the monitoring service
`make up-gateway`	Start the API Gateway
`make up-all`	Start all services
`make down`	Stop all services
`make ps`	Show status of all services
`make logs SERVICE=name`	Show logs for a service (e.g., `make logs SERVICE=auth-service`)
`make restart SERVICE=name`	Restart a service (e.g., `make restart SERVICE=api-gateway`)
`make pull`	Pull latest images for all services
`make build`	Build all services
`make health`	Run health checks for all main services

Example usage:

make up-core
make up-micro
make up-monitoring
make up-gateway
make health
make logs SERVICE=api-gateway
make down

🏗️ Architecture

The AIRIS platform consists of the following microservices:

Core Services

API Gateway (services/api-gateway/) - Main entry point for all API requests
Auth Service (services/auth-service/) - User authentication and authorization
Storage Service (services/storage-service/) - File upload, download, and management
Monitoring Service (services/monitoring-service/) - System metrics, health checks, and alerting

Infrastructure Services

PostgreSQL - Primary database for all services
Redis - Caching and session storage
Prometheus - Metrics collection and monitoring
Grafana - Metrics visualization and dashboards
AlertManager - Alert notification management

🚀 Quick Start

Prerequisites

Docker and Docker Compose
At least 4GB RAM available
Ports 8000, 8001, 8002, 8003, 5432, 6379, 9090, 3000, 9093 available

Development Setup

Clone the repository

git clone <repository-url>
cd airis-platform

Start all services
```
docker-compose up -d
```
Verify services are running
```
docker-compose ps
```
Access the services
- API Gateway: http://localhost:8000
- API Documentation: http://localhost:8000/docs
- Grafana: http://localhost:3000 (admin/admin)
- Prometheus: http://localhost:9090
- AlertManager: http://localhost:9093

📁 Project Structure

airis-platform/
├── services/
│   ├── api-gateway/          # API Gateway service
│   ├── auth-service/         # Authentication service
│   ├── storage-service/      # File storage service
│   └── monitoring-service/   # Monitoring and metrics service
├── monitoring/               # Monitoring configuration
│   ├── prometheus.yml       # Prometheus configuration
│   ├── alertmanager.yml     # AlertManager configuration
│   └── grafana/            # Grafana dashboards and datasources
├── docker-compose.yml       # Service orchestration
├── init-db.sql             # Database initialization
└── README.md               # This file

🔧 Service Details

API Gateway (`services/api-gateway/`)

Purpose: Central entry point for all API requests with routing, authentication, rate limiting, and monitoring.

Features:

Request routing to appropriate microservices
JWT token validation and forwarding
Rate limiting per client IP
Request/response logging
CORS handling
Health checks for all services
Load balancing support

Endpoints:

POST /api/v1/auth/login - User authentication
POST /api/v1/auth/register - User registration
POST /api/v1/storage/upload - File upload
GET /api/v1/storage/download/{file_id} - File download
GET /api/v1/monitoring/metrics - System metrics
GET /api/v1/monitoring/health - Service health status

Auth Service (`services/auth-service/`)

Purpose: Handles user authentication, registration, and JWT token management.

Features:

User registration and login
JWT token generation and validation
Password hashing with bcrypt
Role-based access control
Session management with Redis
Account management

Database: airis_auth schema in PostgreSQL

Storage Service (`services/storage-service/`)

Purpose: Manages file upload, download, and storage operations.

Features:

File upload with size and type validation
File download with streaming
File metadata management
File sharing between users
Storage quota management
Support for local filesystem and S3

Database: airis_storage schema in PostgreSQL

Monitoring Service (`services/monitoring-service/`)

Purpose: Collects system metrics, performs health checks, and manages alerts.

Features:

System metrics collection (CPU, memory, disk)
Service health monitoring
Custom metrics recording
Alert evaluation and management
Prometheus metrics export
Docker container monitoring
Background task management

Database: airis_monitoring schema in PostgreSQL

🔐 Authentication

The system uses JWT (JSON Web Tokens) for authentication:

Login: POST /api/v1/auth/login

{
  "username": "user@example.com",
  "password": "password123"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Using the token: Include in Authorization header

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

📊 Monitoring and Observability

Metrics Collection

Prometheus: Collects metrics from all services
Grafana: Visualizes metrics with pre-configured dashboards
AlertManager: Manages alert notifications

Available Metrics

HTTP request counts and latencies
System resource usage (CPU, memory, disk)
Database connection metrics
Redis cache hit/miss rates
Custom business metrics

Health Checks

Service availability monitoring
Database connectivity checks
Redis connectivity checks
Custom health check endpoints

🗄️ Database Schema

Auth Service Database (`airis_auth`)

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    full_name VARCHAR(255),
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- User sessions table
CREATE TABLE user_sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    session_token VARCHAR(255) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Storage Service Database (`airis_storage`)

-- Files table
CREATE TABLE files (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    filename VARCHAR(255) NOT NULL,
    original_filename VARCHAR(255) NOT NULL,
    file_path VARCHAR(500) NOT NULL,
    file_size BIGINT NOT NULL,
    mime_type VARCHAR(100),
    user_id UUID NOT NULL,
    is_public BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- File shares table
CREATE TABLE file_shares (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    file_id UUID REFERENCES files(id),
    shared_by UUID NOT NULL,
    shared_with UUID NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Monitoring Service Database (`airis_monitoring`)

-- Metrics table
CREATE TABLE metrics (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    metric_name VARCHAR(100) NOT NULL,
    metric_value DOUBLE PRECISION NOT NULL,
    metric_type VARCHAR(50),
    service_name VARCHAR(50),
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Alerts table
CREATE TABLE alerts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    alert_name VARCHAR(100) NOT NULL,
    alert_message TEXT,
    severity VARCHAR(20) NOT NULL,
    status VARCHAR(20) DEFAULT 'active',
    service_name VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    resolved_at TIMESTAMP
);

🚀 Deployment

Development Environment

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Production Environment

# Build production images
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Use production profile
docker-compose --profile production up -d

Environment Variables

Key environment variables for each service:

API Gateway:

ENVIRONMENT: development/production
DEBUG: true/false
REDIS_URL: Redis connection string
AUTH_SERVICE_URL: Auth service URL
STORAGE_SERVICE_URL: Storage service URL
MONITORING_SERVICE_URL: Monitoring service URL

Auth Service:

DATABASE_URL: PostgreSQL connection string
SECRET_KEY: JWT secret key
ALGORITHM: JWT algorithm (HS256)
ACCESS_TOKEN_EXPIRE_MINUTES: Token expiration time

Storage Service:

DATABASE_URL: PostgreSQL connection string
STORAGE_PATH: File storage path
MAX_FILE_SIZE: Maximum file size
ALLOWED_EXTENSIONS: Comma-separated allowed file extensions

Monitoring Service:

DATABASE_URL: PostgreSQL connection string
PROMETHEUS_URL: Prometheus URL
GRAFANA_URL: Grafana URL
ALERTMANAGER_URL: AlertManager URL

🔧 Configuration

Rate Limiting

Default: 60 requests per minute per IP
Configurable per endpoint
Redis-based rate limiting

CORS

Enabled for development
Configurable origins, methods, and headers
Production-ready CORS configuration

Security

JWT-based authentication
Password hashing with bcrypt
HTTPS support (production)
Input validation and sanitization

📈 Performance

Caching Strategy

Redis for session storage
Redis for rate limiting
Redis for metrics caching
File metadata caching

Optimization

Connection pooling for databases
Async/await for I/O operations
Streaming file uploads/downloads
Background task processing

🐛 Troubleshooting

Common Issues

Services not starting

# Check service logs
docker-compose logs <service-name>

# Check service status
docker-compose ps

Database connection issues

# Check PostgreSQL logs
docker-compose logs postgres

# Verify database connectivity
docker-compose exec postgres psql -U airis -d airis

Redis connection issues

# Check Redis logs
docker-compose logs redis

# Test Redis connectivity
docker-compose exec redis redis-cli ping

Monitoring issues

# Check Prometheus logs
docker-compose logs prometheus

# Check Grafana logs
docker-compose logs grafana

Health Checks

API Gateway: GET /health
Auth Service: GET /health
Storage Service: GET /health
Monitoring Service: GET /health

Logs

All services use structured logging with JSON format. Logs can be viewed with:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api-gateway

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

Create an issue in the repository
Check the documentation in each service directory
Review the API documentation at /docs endpoint

AIRIS Platform - A modern, scalable microservices platform built with FastAPI and Docker.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.cursor/rules		.cursor/rules
docs/services		docs/services
monitoring		monitoring
services		services
.gitignore		.gitignore
DEVELOPMENT_PLAN.md		DEVELOPMENT_PLAN.md
GETTING_STARTED.md		GETTING_STARTED.md
Makefile		Makefile
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
development-roadmap.md		development-roadmap.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
env.example		env.example
init-db.sql		init-db.sql
project-structure.md		project-structure.md
start-services.sh		start-services.sh

Folders and files

Latest commit

History

Repository files navigation

AIRIS Microservices Platform

Quickstart: Service Startup Order

1. Core Infrastructure

2. Core Microservices

3. Monitoring Service

4. API Gateway

Makefile Shortcuts

🏗️ Architecture

Core Services

Infrastructure Services

🚀 Quick Start

Prerequisites

Development Setup

📁 Project Structure

🔧 Service Details

API Gateway (services/api-gateway/)

Auth Service (services/auth-service/)

Storage Service (services/storage-service/)

Monitoring Service (services/monitoring-service/)

🔐 Authentication

📊 Monitoring and Observability

Metrics Collection

Available Metrics

Health Checks

🗄️ Database Schema

Auth Service Database (airis_auth)

Storage Service Database (airis_storage)

Monitoring Service Database (airis_monitoring)

🚀 Deployment

Development Environment

Production Environment

Environment Variables

🔧 Configuration

Rate Limiting

CORS

Security

📈 Performance

Caching Strategy

Optimization

🐛 Troubleshooting

Common Issues

Health Checks

Logs

🤝 Contributing

📄 License

🆘 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

API Gateway (`services/api-gateway/`)

Auth Service (`services/auth-service/`)

Storage Service (`services/storage-service/`)

Monitoring Service (`services/monitoring-service/`)

Auth Service Database (`airis_auth`)

Storage Service Database (`airis_storage`)

Monitoring Service Database (`airis_monitoring`)

Packages