CLAUDE.md Template: FastAPI + Cassandra DB + Cassandra-Driver + Firebase Auth Microservice

Overview

CLAUDE.md template for a FastAPI microservice backed by Cassandra DB using Cassandra-Driver and Firebase Auth. It provides a practical blueprint to build a secure, typed API with clear separation of concerns, suitable for production-grade microservices.

Direct answer: This CLAUDE.md Template configures a FastAPI+ Cassandra+ Firebase Auth microservice with strict data modeling, token verification, and testable architecture that you can paste directly into CLAUDE.md.

When to Use This CLAUDE.md Template

• You need a FastAPI REST API backed by Cassandra for scalable writes and reads.
• You require Firebase ID token verification for per-request authentication.
• You want a clean project structure with clear separation of concerns (api, db, auth, services).
• You must avoid opaque dependencies and ensure testable, production-grade code.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, a developer assistant that writes production-ready CLAUDE.md templates for Python FastAPI microservices backed by Cassandra and Firebase Auth.

Architecture rules:
- Use a single FastAPI app instance with dependency injection for DB and auth.
- All business logic should live in services, not in route handlers.
- Use a dedicated auth middleware to verify Firebase ID tokens on protected routes.
- Separate Cassandra access layer (db) from API routes (api).
- Use prepared statements for all Cassandra queries and bind parameters safely.
- Run Cassandra queries in a threadpool if used in async endpoints.
- Centralize configuration via environment variables, not code.

File structure rules:
- app/           # FastAPI app and source
- app/main.py    # FastAPI startup and route inclusion
- app/api/       # API routers and endpoints
- app/api/v1/    # Versioned API endpoints
- app/db/        # Cassandra connection and models
- app/db/cassandra.py
- app/auth/      # Firebase auth helpers
- app/auth/firebase.py
- app/services/  # Business logic services
- app/models/    # Pydantic models and schemas
- config.py      # App config and environment loading
- tests/         # Tests
- requirements.txt
- Dockerfile
- docker-compose.yml (optional in dev)

Authentication rules:
- Validate Firebase ID tokens via Firebase Admin SDK using a service account key from env var.
- Expect Authorization: Bearer  header on protected endpoints.
- On token verification failure, return 401 with a clear error message.

Database rules:
- Cassandra keyspace and tables must be created in advance (or via migrations).
- Use prepared statements with bound variables for all queries.
- Use a reasonable read/write consistency level (e.g., QUORUM) and token-aware routing.
- Use TTL for ephemeral data where applicable.

Validation rules:
- Use Pydantic models for request bodies and responses.
- Validate all inputs (types, required fields, length constraints).
- Normalize strings (strip, lower-case when appropriate) before persisting.

Security rules:
- Do not commit secrets to code; use environment variables.
- Do not disable certificate verification in production; enable TLS for Cassandra and HTTP.
- Do not expose raw Cassandra errors to clients; map errors to meaningful HTTP status codes.

Testing rules:
- Unit tests for validators and services with mocks for Cassandra and Firebase.
- Integration tests for endpoints with a test Cassandra instance and Firebase admin initialized.
- CI must run pytest with coverage thresholds.

Deployment rules:
- Use Docker to containerize the FastAPI app and Cassandra cluster in development.
- Use environment variables for credentials and endpoints (CASSANDRA_CONTACT_POINTS, FIREBASE_PROJECT_ID, etc.).
- Ensure the app starts with uvicorn --host 0.0.0.0 --port 8000 --reload (dev) or proper ASGI server in prod.

Things Claude must not do:
- Do not generate code that bypasses token verification or security controls.
- Do not embed plaintext credentials in the CLAUDE.md template.
- Do not use non-parameterized queries against Cassandra.
- Do not introduce custom, unscoped global singletons without lifetime management.

Recommended Project Structure

fastapi-cassandra-firebase-claude-md-template/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1/
│   │       └── endpoints.py
│   ├── models/
│   │   └── schemas.py
│   ├── db/
│   │   ├── cassandra.py
│   │   └── models.py
│   ├── auth/
│   │   └── firebase.py
│   ├── services/
│   │   └── user_service.py
│   └── config.py
├── tests/
│   ├── test_endpoints.py
│   └── test_integration.py
├── requirements.txt
├── Dockerfile
└── .env

Core Engineering Principles

• Single responsibility: separate concerns among API, DB, and auth layers.
• Explicit typing and schema validation with Pydantic.
• Defensive coding: validate, normalize, and sanitize inputs.
• Security-by-default: verify tokens, never trust client data, and protect secrets.
• Testability: isolate dependencies and provide mocks/stubs for external services.
• Observability: structured logging and simple tracing hooks for requests.

Code Construction Rules

• Connect to Cassandra via cassandra-driver with a dedicated cluster object created from env vars.
• Use prepared statements for all queries and bind parameters safely.
• Keep Cassandra sessions per-process; avoid per-request creation overhead.
• Authenticate requests by verifying Firebase ID tokens and extracting user claims.
• Model API payloads with Pydantic and respond with strict schemas.
• Handle timezones consistently; store timestamps in UTC.
• Fail fast on invalid inputs; return meaningful HTTP status codes.

Security and Production Rules

• Never commit secrets in code; read from environment variables or secret stores.
• Enable TLS for HTTP endpoints and for Cassandra client connections when possible.
• Validate Firebase tokens server-side and reject invalid tokens immediately.
• Limit request sizes and implement rate limiting where appropriate.
• Monitor and rotate service account credentials regularly.

Testing Checklist

• Unit tests for validators and services with mocks for Cassandra and Firebase.
• Integration tests for endpoints with a test Cassandra cluster and Firebase Admin initialized.
• Test token verification for valid and invalid tokens.
• End-to-end tests for create/read/update/delete flows.
• Ensure CI runs pytest with coverage thresholds.

Common Mistakes to Avoid

• Forgetting to verify Firebase ID tokens on protected routes.
• Using raw string queries instead of prepared statements with Cassandra.
• Holding Cassandra sessions across process lifetimes without proper closure.
• Storing credentials in code or logs.
• Neglecting proper error handling and logging in production.

FAQ

• What is included in this CLAUDE.md Template? A ready-to-paste CLAUDE.md template block plus stack-specific guidance for FastAPI + Cassandra + Cassandra-Driver + Firebase Auth microservice.
• Is Firebase used for authentication? Yes. The template verifies Firebase ID tokens via the Firebase Admin SDK.
• How is Cassandra modeled? Keyspace and tables designed for typical microservice patterns with prepared statements and TTL.
• How do I run tests? Install dependencies, configure environment variables for Cassandra and Firebase, and run pytest.
• What should I avoid? Do not hardcode secrets, bypass token verification, or use unparameterized queries.