CLAUDE.md Template for FastAPI + ClickHouse + Firebase Auth + ClickHouse Connect Stream

Overview

This CLAUDE.md template provides a field-tested CLAUDE.md block for building a FastAPI application that streams data to ClickHouse using ClickHouse Connect Stream, with Firebase Authentication. It targets Claude Code workflows for API endpoints, streaming ingestion, and real-time analytics power.

When to Use This CLAUDE.md Template

• You are building a FastAPI service that ingests and streams data into ClickHouse in real time.
• You require Firebase authentication to secure API endpoints and verify user tokens before processing data.
• You want a reproducible CLAUDE.md template that codifies architecture, security, testing, and deployment rules for this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a Claude Code architect building a FastAPI service that streams data into ClickHouse via ClickHouse Connect Stream and authenticates users with Firebase Auth. Optimize for clarity, security, and reproducibility.

Architecture rules:
- FastAPI app with Pydantic models for validation
- ClickHouse as the OLAP store, Write-Through streaming via ClickHouse Connect Stream
- Firebase Auth for user authentication and token verification
- Stateless API endpoints with token verification on each request
- Observability via structured logs and metrics

File structure rules:
- app/
  - main.py
  - api/
    - v1/
      - endpoints/
        - streaming.py
        - items.py
  - core/
    - config.py
    - security.py
  - db/
    - clickhouse_client.py
    - clickhouse_stream.py
  - models/
    - schemas.py
  - firebase/
    - auth.py
  - streams/
    - stream_consumer.py
- tests/
- config/
- docker-compose.yml
- Dockerfile
- requirements.txt

Authentication rules:
- Endpoints require Authorization header with Bearer token
- Validate Firebase ID tokens using Firebase Admin SDK keys or Google public keys
- Reject requests with missing or invalid tokens (HTTP 401)
- Map token claims to access privileges and enforce least privilege

Database rules:
- Use ClickHouse DB and a write-optimized table for streaming data
- Use a streaming client via ClickHouse Connect Stream; handle backpressure and retries
- Ensure idempotent writes where possible, with unique keys to avoid duplicates

Validation rules:
- Validate request bodies with Pydantic models
- Normalize and type-check all inputs; reject invalid payloads early

Security rules:
- Do not log full tokens or sensitive payloads
- Use environment-based configuration for DB credentials and Firebase credentials
- Enforce TLS for all external traffic

Testing rules:
- Unit tests for validation logic and utility functions
- Integration tests for Firebase token verification and ClickHouse streaming path
- End-to-end tests for a minimal ingestion path

Deployment rules:
- Use Uvicorn with Gunicorn or an ASGI server, with proper worker counts
- Run in containers with strict resource limits
- Use secret management and environment variables for credentials

Things Claude must not do:
- Do not hard-code secrets in code blocks
- Do not bypass authentication checks
- Do not assume network availability without retry logic

Related implementation resources: AI Agent Use Case for Tax Advisors Using Client Documents to Identify Missing Tax Filing Information and StreamText and StreamObject: Reducing initial latency in production AI pipelines.