CLAUDE.md Template for Fullstack Next.js 15 & FastAPI Monorepo

What is this CLAUDE.md template for?

This CLAUDE.md template orchestrates your AI coding assistant to operate fluidly across a dual-language, state-of-the-art fullstack environment. It bridges the architectural gap between a performance-obsessed Next.js 15 frontend (utilizing Server Components, Tailwind CSS, and Shadcn UI) and a scalable async FastAPI backend.

It eliminates contextual confusion when the AI switches files, ensuring that frontend changes adhere strictly to React Server Components (RSC) architecture while backend tasks employ Python async/await, Pydantic validation, and clean repository layers.

When to use this template

Use this template when building end-to-end SaaS products, complex web tools, dashboard ecosystems, or multi-agent AI web platforms where heavy AI/data workloads live on a Python backend but require a real-time, highly polished Web Vitals-perfect user interface.

Recommended project structure

project-root/
  backend/
    app/
      api/
      models/
      schemas/
      services/
      main.py
    requirements.txt
  frontend/
    src/
      app/
      components/
        ui/
      lib/
    package.json
    tailwind.config.ts
  CLAUDE.md
  README.md

CLAUDE.md Template

# CLAUDE.md: Fullstack Next.js & FastAPI Architecture Guide

You are acting as an Elite Fullstack Systems Architect specialized in high-performance web applications and asynchronous Python systems.

You guide code generation across a dual-runtime monorepo consisting of a Next.js 15 frontend and an asynchronous FastAPI backend.

## Core Fullstack Principles

- **Strict Context Aware Execution**: Always respect runtime boundaries. Do not inject Node modules into the Python backend, and do not use Python dependencies or syntax within the TypeScript frontend.
- **Contract-Driven Boundaries**: Treat the FastAPI REST API layer as the source of truth. All frontend API interaction shapes must mirror backend Pydantic schemas accurately.
- **Performance Obsession**: Enforce clean code paths that target 100% Lighthouse metrics (Performance, SEO, Accessibility, Best Practices) in the frontend and minimal microsecond response loops in the backend.

## Frontend Standards (Next.js 15, Tailwind, Shadcn)

### 1. Architectural Strategy
- By default, use React Server Components (RSC) for data fetching and view assembly to minimize client bundle footprints.
- Use the `'use client'` directive selectively for high-fidelity interactive elements, form states, and client-side context provisions.
- Leverage modern Next.js 15 routing, layout composition, and native loading/error error boundary fallbacks.

### 2. Styling & Interface
- Utilize Tailwind CSS utilities cleanly without inline styling. Write modern, responsive design structures.
- Consume and extend Shadcn UI component abstractions consistently. Ensure high compliance with keyboard navigation and ARIA web accessibility rules.

## Backend Standards (FastAPI Async)

### 1. Async Optimization
- Build high-throughput, non-blocking asynchronous endpoints utilizing modern `async def` declarations.
- Use Pydantic v2 schemas rigorously for request data modeling, payload extraction, and data mapping.

### 2. Directory Isolation
- Keep application configuration decoupled via Pydantic Settings, database pooling contexts isolated, and pure business workflow actions separated entirely from HTTP controller handlers.

## Cross-Boundary Coordination Workflow

When writing a feature spanning both domains, strictly follow this execution order:
1. Update or create the database entities and Pydantic schema representations.
2. Implement and test the async FastAPI router path and ensure payload data maps correctly.
3. Verify the mock or live JSON response structures align with frontend expectations.
4. Build or update the matching TypeScript interfaces matching the API payload.
5. Assemble the Next.js UI using Server Components for page-level structural fetching and clean client components for user input actions.

## Quality & Verification Requirements
- Keep variable naming conventions native to their ecosystem: `snake_case` in Python, `camelCase` in TypeScript.
- Ensure missing environment credentials fall back safely without crashing build matrices or deployment runbooks.
- Prevent error details from displaying internal DB fields or security secrets to final users.

Why this template matters

AI assistants frequently lose architectural focus in monorepos. They accidentally write TypeScript patterns inside Python services or mix up client/server boundaries in Next.js 15. This specific template provides an unambiguous set of rules that forces the AI to check its runtime context before writing code.

It explicitly keeps code quality aligned to modern production standards, resulting in full-stack components that integrate flawlessly with excellent performance, data safety, and zero structural conflicts.

Recommended additions

• Add a script framework instruction for automated TypeScript interface generation directly from backend Pydantic schemas.
• Integrate shared development commands (e.g., using a root Makefile or turbo pipeline task manager).
• Define global unified Docker compose blueprints for concurrent frontend and backend orchestration.
• Incorporate specific configuration layers for unified authentication engines like NextAuth/Auth.js mapping down to FastAPI.

FAQ

How does this template maintain sync between Python schemas and TypeScript types?

It sets down explicit contract-driven rules, instructing the assistant to treat the backend's Pydantic schemas as the master data blueprint, matching fields directly across language boundaries during feature development.

Is this setup optimized for high Lighthouse performance scores?

Yes. By forcing the assistant to maximize React Server Components (RSC) and leverage Tailwind CSS/Shadcn UI patterns correctly, client-side bundle bloat is heavily reduced, allowing for peak performance scores.

Can this handle independent deployments of frontend and backend?

Absolutely. The directory layout ensures clean physical and logical separation, allowing the backend to deploy on a service like AWS/GCP and the frontend to deploy seamlessly on Vercel or similar runtimes.

How does it prevent runtime boundary leakage?

The Monorepo context guard rules explicitly warn the AI system to separate the Node runtime context from the Python application engine, completely stopping mixed-language code generation bugs.

About the author

Suhas Bhairav is a systems architect and applied AI researcher focused on production-grade AI systems, RAG, knowledge graphs, AI agents, and enterprise AI implementation.