This document provides the complete, detailed, and production-ready code scaffold for a new microservice. This output is designed to be a foundational template, ready for immediate development and deployment.
This deliverable provides a comprehensive scaffold for a new microservice, encompassing core application logic, API definitions, database interactions, Dockerization, testing infrastructure, CI/CD pipeline configuration, and basic deployment scripts.
To provide a robust and widely applicable example, we have chosen the following technology stack:
This stack offers excellent developer experience, performance, and scalability for modern microservices.
The generated microservice follows a standard and organized project structure:
. ├── .github/ # GitHub specific configurations │ └── workflows/ # CI/CD workflows │ └── main.yml # Main CI/CD pipeline for build, test, deploy ├── app/ # Main application source code │ ├── api/ # API endpoints definitions │ │ └── v1/ │ │ └── endpoints.py # API routes for version 1 │ ├── crud/ # Create, Read, Update, Delete operations │ │ └── __init__.py │ │ └── item.py # CRUD operations for Item model │ ├── core/ # Core application utilities and configurations │ │ ├── config.py # Application settings │ │ ├── database.py # Database connection and session management │ │ └── security.py # (Placeholder for security utilities) │ ├── db/ # Database related scripts and migrations │ │ └── alembic/ # Alembic migration environment │ │ └── versions/ # Migration scripts │ │ └── env.py │ │ └── script.py.mako │ │ └── alembic.ini # Alembic configuration │ │ └── base_class.py # Base for SQLModel models │ ├── models/ # Database models │ │ └── item.py # Item model definition │ │ └── __init__.py │ ├── schemas/ # Pydantic schemas for request/response validation │ │ └── item.py # Item schemas (create, update, read) │ │ └── __init__.py │ ├── services/ # Business logic services │ │ └── item_service.py # Business logic for items │ │ └── __init__.py │ └── main.py # FastAPI application entry point ├── tests/ # Unit and integration tests │ └── conftest.py # Pytest fixtures │ └── test_api_items.py # Tests for Item API endpoints ├── .dockerignore # Files/directories to ignore when building Docker image ├── .env.example # Example environment variables ├── Dockerfile # Docker image definition ├── docker-compose.yml # Docker Compose for local development environment ├── Makefile # Common development commands ├── pyproject.toml # Poetry/PEP 621 project configuration ├── README.md # Project documentation ├── requirements.txt # Python dependencies (generated from pyproject.toml)
Workflow Description: Generate a complete microservice with Docker setup, API routes, database models, tests, CI/CD pipeline config, and deployment scripts.
Current Step: gemini → plan_architecture
This document outlines the comprehensive architectural plan for the microservice to be scaffolded. This plan will serve as the blueprint for subsequent steps, ensuring a robust, scalable, maintainable, and deployable service.
Project Goal: To establish a foundational architecture for a new microservice, enabling rapid development, consistent quality, and streamlined deployment.
Architectural Principles:
This section details the internal structure and key components of the microservice.
To provide a concrete and modern scaffold, we recommend the following default stack. This can be customized in subsequent steps.
* Rationale: High performance (ASGI), excellent developer experience, automatic OpenAPI (Swagger) documentation generation, strong type hinting support.
* Rationale: Robust, open-source, ACID-compliant relational database, widely supported.
* Rationale: Powerful and flexible ORM for Python, robust migration tool.
* Rationale: Modern dependency managers for Python, offering isolated environments and reproducible builds.
/api/v1/resource). * /api/v1/[resource]: Collection resources (e.g., /api/v1/users).
* /api/v1/[resource]/{id}: Specific resource instance (e.g., /api/v1/users/123).
* GET: Retrieve resources.
* POST: Create new resources.
* PUT/PATCH: Update existing resources.
* DELETE: Remove resources.
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error). * Flow: User authenticates with an identity provider (or directly with the service), receives a JWT, and includes it in subsequent requests via the Authorization: Bearer <token> header.
logging module, directed to stdout/stderr for collection by container orchestration logs.* Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL.
* Metrics: Prometheus-compatible metrics exposed via an /metrics endpoint (e.g., request count, latency, error rates, resource utilization).
* Health Checks: /health and /ready endpoints for liveness and readiness probes in container orchestration.
BaseSettings for loading and validating environment variables into a structured configuration object.This section details the infrastructure, build, test, and deployment strategies.
* Multi-stage builds for smaller image sizes and improved security.
* Utilizes a lightweight base image (e.g., Alpine Linux).
docker-compose.yml for local development setup, including:* The microservice itself.
* A PostgreSQL database container.
* (Optional) A local Redis instance for caching/Celery broker.
* (Optional) Adminer/pgAdmin for database management.
A robust CI/CD pipeline ensures automated testing, building, and deployment.
push to main branch, and pull requests to main.1. Build: Install dependencies, compile (if applicable), lint, format.
2. Test: Run unit, integration, and (optionally) end-to-end tests.
3. Security Scan: Static Application Security Testing (SAST) tools (e.g., Bandit for Python).
4. Container Build & Push: Build Docker image, tag with commit SHA/version, push to Container Registry (e.g., Docker Hub, AWS ECR, GCP Container Registry).
5. Deployment (Optional for CI, part of CD): Trigger deployment to staging/production environments.
* Framework: pytest with pytest-asyncio for asynchronous code.
* Coverage: Aim for high code coverage (e.g., 80%+).
* Framework: pytest using FastAPI's TestClient.
* Database: Use a dedicated test database or in-memory database for faster execution.
* Framework: Playwright, Cypress, or similar.
* Tools: Black, Flake8, isort.
* Recommended: Kubernetes (EKS/GKE/AKS) or AWS ECS/Fargate.
* Kubernetes: Helm charts for packaging and deploying the microservice.
* ECS/Fargate: AWS CloudFormation or Terraform for infrastructure as code, defining task definitions and services.
* Development: Local Docker Compose.
* Staging/UAT: A pre-production environment for testing and user acceptance.
* Production: The live environment.
This architectural plan provides the foundation for the following deliverables in the subsequent scaffolding steps:
Dockerfile and docker-compose.yml.README.md with setup instructions and API documentation via OpenAPI.It appears your request included a query for a "detailed study plan." Please note that the current workflow, "Microservice Scaffolder," is designed to generate microservice components and related infrastructure, not educational study plans.
For this current step, I have focused entirely on delivering the comprehensive microservice architecture plan as requested. If you require a study plan, please initiate a new, separate workflow specifically for that purpose.
python
from typing import List, Optional
from sqlmodel import Session, select
from app.models.item import Item
from app.schemas.item import ItemCreate, ItemUpdate
def create_item(session: Session, item_in: ItemCreate) -> Item:
"""
Creates a new item in the database.
"""
item = Item.model_validate(item_in) # Converts Pydantic schema to SQLModel instance
session.add(item)
session.commit()
session.refresh(item) # Refresh to get auto-generated ID and timestamps
return item
def get_item(session: Session, item_id: int) -> Optional[Item]:
"""
Retrieves a single item by its ID.
"""
return session.get(Item, item_id)
def get_items(session: Session, skip: int = 0, limit: int = 100) -> List[Item]:
"""
Retrieves a list of items from the database.
"""
statement = select(Item).offset(skip).limit(limit)
return session.exec(statement).all()
def update_item(session: Session, item_id: int, item_in: ItemUpdate) -> Optional[Item]:
"""
Updates an existing item in the database.
"""
item = session.get(Item, item_id)
if not item:
return None
# Update fields from the input schema
# Use .model_dump(exclude_unset=True) to only update fields that were provided
update_data = item_in.model_dump(exclude_unset=True)
for key, value
This document provides a comprehensive overview and detailed documentation for the newly generated microservice. This output is the result of the "Microservice Scaffolder" workflow, successfully completing the review_and_document step.
The generated microservice is designed for rapid development, robust operation, and seamless integration into a modern cloud-native environment. It includes a complete set of components, from API routes and database models to Dockerization, testing, and CI/CD pipeline configurations.
Your new microservice is built with a modern, asynchronous Python stack, optimized for performance and developer experience.
Technology Stack:
Key Features:
The scaffolded project follows a modular and organized structure to enhance readability, maintainability, and scalability.
.
├── .github/ # GitHub Actions CI/CD workflows
│ └── workflows/
│ ├── ci.yml # Continuous Integration (build, test, lint)
│ └── cd.yml # Continuous Deployment (placeholder)
├── deploy/ # Deployment configurations and scripts
│ ├── kubernetes/ # Kubernetes manifests
│ │ ├── deployment.yaml
│ │ └── service.yaml
│ └── scripts/ # Utility deployment scripts
│ └── deploy_to_cloud.sh # Example cloud deployment script
├── src/ # Core microservice source code
│ ├── api/ # API routes and endpoint definitions
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── items.py # Example CRUD for 'items'
│ │ └── users.py # Example CRUD for 'users'
│ ├── core/ # Core configurations and utilities
│ │ ├── config.py # Application settings
│ │ └── security.py # Security utilities (e.g., password hashing)
│ ├── database/ # Database connection and ORM setup
│ │ ├── migrations/ # Alembic migration scripts
│ │ │ ├── versions/ # Generated migration files
│ │ │ └── env.py
│ │ ├��─ __init__.py
│ │ ├── base.py # Base for SQLAlchemy declarative models
│ │ └── session.py # Database session management
│ ├── models/ # SQLAlchemy ORM models
│ │ ├── __init__.py
│ │ ├── item.py
│ │ └── user.py
│ ├── schemas/ # Pydantic schemas for request/response validation
│ │ ├── __init__.py
│ │ ├── item.py
│ │ └── user.py
│ ├── services/ # Business logic and service layer
│ │ ├── __init__.py
│ │ ├── item.py
│ │ └── user.py
│ └── main.py # FastAPI application entry point
├── tests/ # Unit and integration tests
│ ├── conftest.py # Pytest fixtures
│ ├── unit/
│ │ ├── test_models.py
│ │ └── test_services.py
│ └── integration/
│ └── test_api.py
├── .dockerignore # Files to ignore when building Docker image
├── .env.example # Example environment variables
├── .gitignore # Git ignore file
├── Dockerfile # Docker image definition
├── docker-compose.yml # Local development environment with Docker
├── README.md # Project README
├── requirements.txt # Python dependencies
└── alembic.ini # Alembic configuration for migrations
src/)src/main.py: The main entry point for your FastAPI application. It initializes the FastAPI app, includes API routers, and sets up event handlers (e.g., database connection lifecycle).
# Example src/main.py snippet
from fastapi import FastAPI
from src.api.v1 import users, items
from src.core.config import settings
from src.database.session import engine, Base
app = FastAPI(
title=settings.PROJECT_NAME,
version=settings.API_VERSION,
openapi_url=f"{settings.API_V1_STR}/openapi.json"
)
# Include API routers
app.include_router(users.router, prefix=settings.API_V1_STR, tags=["users"])
app.include_router(items.router, prefix=settings.API_V1_STR, tags=["items"])
@app.on_event("startup")
async def startup_event():
# Optional: Create all database tables if they don't exist
# Base.metadata.create_all(bind=engine)
print("Application startup")
@app.on_event("shutdown")
async def shutdown_event():
print("Application shutdown")
# Access API docs at /docs or /redoc
src/api/v1/: Contains endpoint definitions for version 1 of your API. Each file (e.g., items.py, users.py) defines a APIRouter with specific routes, dependencies, and response models.
# Example src/api/v1/users.py snippet
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from typing import List
from src.schemas import user as user_schemas
from src.services import user as user_services
from src.database.session import get_db
router = APIRouter()
@router.post("/", response_model=user_schemas.User, status_code=status.HTTP_201_CREATED)
def create_user(user: user_schemas.UserCreate, db: Session = Depends(get_db)):
db_user = user_services.get_user_by_email(db, email=user.email)
if db_user:
raise HTTPException(status_code=400, detail="Email already registered")
return user_services.create_user(db=db, user=user)
@router.get("/", response_model=List[user_schemas.User])
def read_users(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
users = user_services.get_users(db, skip=skip, limit=limit)
return users
src/models/: Defines your SQLAlchemy ORM models, representing database tables.
# Example src/models/user.py snippet
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import relationship
from src.database.base import Base
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True, index=True)
email = Column(String, unique=True, index=True, nullable=False)
hashed_password = Column(String, nullable=False)
is_active = Column(Boolean, default=True)
items = relationship("Item", back_populates="owner")
src/schemas/: Contains Pydantic models used for validating request bodies, structuring response data, and defining data shapes throughout the application.
# Example src/schemas/user.py snippet
from pydantic import BaseModel, EmailStr
from typing import List, Optional
class UserBase(BaseModel):
email: EmailStr
class UserCreate(UserBase):
password: str
class User(UserBase):
id: int
is_active: bool
# items: List[Item] = [] # Uncomment if you want to embed items in user response
class Config:
orm_mode = True # Enable ORM mode for SQLAlchemy integration
src/services/: Encapsulates the business logic, interacting with the database through the ORM models. This separation keeps your API routes clean and focused on request/response handling.
# Example src/services/user.py snippet
from sqlalchemy.orm import Session
from src.models import user as user_model
from src.schemas import user as user_schemas
from src.core.security import get_password_hash
def get_user(db: Session, user_id: int):
return db.query(user_model.User).filter(user_model.User.id == user_id).first()
def get_user_by_email(db: Session, email: str):
return db.query(user_model.User).filter(user_model.User.email == email).first()
def get_users(db: Session, skip: int = 0, limit: int = 100):
return db.query(user_model.User).offset(skip).limit(limit).all()
def create_user(db: Session, user: user_schemas.UserCreate):
hashed_password = get_password_hash(user.password)
db_user = user_model.User(email=user.email, hashed_password=hashed_password)
db.add(db_user)
db.commit()
db.refresh(db_user)
return db_user
src/core/config.py: Manages application settings, typically loaded from environment variables.
# Example src/core/config.py snippet
from pydantic import BaseSettings, Field
class Settings(BaseSettings):
PROJECT_NAME: str = "MyMicroservice"
API_VERSION: str = "0.1.0"
API_V1_STR: str = "/api/v1"
DATABASE_URL: str = Field(..., env="DATABASE_URL")
SECRET_KEY: str = Field(..., env="SECRET_KEY")
ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
class Config:
env_file = ".env"
env_file_encoding = 'utf-8'
settings = Settings()
src/database/)src/database/session.py: Configures the SQLAlchemy engine and provides a dependency for obtaining a database session within your API routes.src/database/base.py: Defines the Base class for your SQLAlchemy declarative models.src/database/migrations/: This directory is managed by Alembic.*`alembic.ini