Production-Ready Template for AI/LLM Applications: Full-Stack-AI-Agent + Next.js + 20+ Integrations

At Vstorm, we have built production AI systems using FastAPI, PydanticAI, LangChain, and Next.js for manufacturing companies, enterprises and startups. After the tenth project starting with the same boilerplate, setting up JWT authentication, WebSocket streaming, database migrations, Logfire observability, we had to ask ourselves: why are we solving the same problems over and over again?

Every AI application needs the same foundations: authentication with JWT tokens and refresh logic, real-time streaming over WebSockets, conversation persistence in PostgreSQL or MongoDB, observability through Logfire or LangSmith, deployment with Docker and CI/CD pipelines. The essential building blocks.

And yet we were spending weeks on infrastructure before being able to write a single line of business logic.

So we decided to address this chokepoint once and for all. The result is the full-stack-ai-agent-template , an open-source CLI tool that generates production-ready full-stack applications combining FastAPI, Next.js 15, and your choice of PydanticAI or LangChain for AI agents. One command gives you WebSocket streaming, JWT authentication, database setup with Alembic migrations, Redis caching, Logfire tracing, and Docker deployment.

When we released it, the response was immediate. One developer on Reddit summed it up perfectly:

"For anyone building with FastAPI, this template is a game-changer — it just cut my AI project setup from months to hours."

This article explains what we built, the architectural decisions behind it, and how you can use it to ship your AI applications faster

The problem: every AI project starts the same way #

Building an AI application is not just about wrapping up an OpenAI or Anthropic API. When a user asks your PydanticAI-powered chatbot a question, you need to:

1. Authenticate the request: JWT validation, refresh tokens, or API keys
2. Stream the response: WebSocket connections so users see text as it generates
3. Handle tool calls: Modern agents using PydanticAI or LangChain call tools, and users need transparency
4. Persist conversations: PostgreSQL or MongoDB storage so users continue where they left off
5. Monitor everything: Logfire traces, Sentry errors, Prometheus metrics for production visibility

Each requirement demands infrastructure. JWT authentication means secure password hashing with bcrypt, token generation, refresh logic, and HTTP-only cookies. WebSocket streaming means connection lifecycle management, graceful disconnection handling, and event serialization. Database persistence means SQLAlchemy models, Alembic migrations, and the repository pattern. Observability means OpenTelemetry instrumentation across FastAPI, asyncpg, Redis, and PydanticAI.

We have seen teams spend three months building this infrastructure before writing their first AI feature. We have seen startups burn runway on solved these problems. We have seen enterprises pay consulting fees for boilerplate code that every project needs.

This was the pain we set out to eliminate.

FastAPI + Next.js + PydanticAI: what is included #

The fastapi-full-stack-ai-agent-template is an interactive CLI that generates complete full-stack projects tailored to your requirements. It is not a library you import, it is a Cookiecutter-based generator that creates a standalone, fully-owned codebase.

# Install and run pip install full-stack-ai-agent-template full-stack-ai-agent-template new The interactive wizard guides you through + configuration options including database authentication AI framework and observability In under a minute, you have a complete project structure:

my_ai_app/ ├── backend/ │ ├── app/ │ │ ├── api/routes/v1/ # FastAPI HTTP endpoints │ │ ├── agents/ # PydanticAI or LangChain agents │ │ ├── services/ # Business logic layer │ │ ├── repositories/ # SQLAlchemy/MongoDB data access │ │ ├── schemas/ # Pydantic request/response models │ │ ├── db/models/ # SQLAlchemy or MongoDB models │ │ ├── core/ # Config, JWT security, middleware │ │ └── worker/ # Celery/Taskiq background tasks │ ├── tests/ # Pytest with async fixtures │ └── alembic/ # Database migrations ├── frontend/ │ ├── src/ │ │ ├── app/ # Next.js 15 App Router │ │ ├── components/chat/ # React chat interface │ │ └── hooks/ # WebSocket, React Query hooks │ └── e2e/ # Playwright E2E tests ├── docker-compose.yml # PostgreSQL, Redis, app services ├── Makefile # Development commands └── README.md The generated code is not scaffolding that you have to fill in. It is working, tested code with Logfire instrumentation, Docker configuration, and production settings. Run make install && make run , and you have a live FastAPI + Next.js application.

Try it now: pip install fastapi-fullstack && fastapi-fullstack new — generate your first full-stack AI project in under a minute.

20+ enterprise integrations

We did not want to build another minimal template. We wanted to build what production AI applications actually need.

Every integration is optional. Want a minimal FastAPI without authentication? Use --minimal . Want the full production stack with PostgreSQL, Redis, Celery, and Logfire? Use --preset production . The Cookiecutter generator creates exactly what you need

Project architecture: repository pattern + Pydantic Settings #

Template projects often fail because they are either too simple (hello world with SQLAlchemy) or too complex (enterprise monolith with unnecessary abstractions). We aimed for the middle ground: patterns that scale without complexity overhead.

Repository + service pattern with SQLAlchemy

In every generated project, data access flows through three layers:

• FastAPI Route → Service
• Service → Repository
• Repository → Database

Repositories handle data access using SQLAlchemy (for PostgreSQL/SQLite) or Motor (for MongoDB). They provide generic CRUD operations plus model-specific queries. They know about async sessions, query optimization, and database specifics. They do not know about business rules.

Services handle business logic. They orchestrate repositories, enforce rules, validate state, and raise domain exceptions like NotFoundError or AlreadyExistsError . When a user registers, the service checks for existing emails, hashes the password with bcrypt, and calls the repository to persist.

A critical implementation detail: repositories use db.flush() instead of db.commit() . This keeps SQLAlchemy transactions open so services can orchestrate multiple repository calls atomically. The FastAPI route handler commits the transaction at the end, ensuring all-or-nothing semantics.

This pattern enables easy testing: mock the repository to test service logic without PostgreSQL. It improves maintainability: database changes do not ripple through business logic. And it provides flexibility: swap PostgreSQL for MongoDB by implementing a new repository while keeping services unchanged.

Pydantic Settings with production validation

Configuration lives in a single Pydantic Settings class that validates environment variables at startup. Database URLs are computed from components using @computed_field , so you configure POSTGRES_HOST and POSTGRES_PASSWORD rather than constructing connection strings manually.

The critical feature is production validation. The settings class includes @field_validator decorators that prevent common deployment mistakes: using default JWT secrets in production, enabling wildcard CORS origins, or leaving debug mode on. These Pydantic validators have caught real issues in client deployments.

Cookiecutter with Jinja2 conditionals

We use Cookiecutter with Jinja2 conditionals rather than a monorepo with runtime feature flags. When you generate a project without Redis, there are no Redis imports anywhere in your FastAPI code. Your pyproject.toml only includes the dependencies you selected. The generated code is yours to own and modify.

The template contains nearly 100 configuration variables covering every integration. A post-generation hook cleans up unused files and runs formatters (Ruff for Python, Prettier for TypeScript), so the generated code is immediately production-ready.

AI Agent integration: PydanticAI & LangChain #

AI capabilities are not an afterthought bolted onto a generic FastAPI template. They are the reason we built this.

Framework choice: PydanticAI vs LangChain

We support both frameworks because they serve different needs.

PydanticAI is our recommended choice for new projects. Built by the Pydantic team, it offers full type safety with Pyright strict mode, native Logfire integration for observability, and a simpler mental model than graph-based frameworks. Its iter() method provides first-class streaming support with access to every event the model produces: text deltas, tool calls, and results.

LangChain makes sense when you need its ecosystem: the extensive tool library, LangSmith for tracing and evaluation, or familiarity for teams already using it.

The generated code structure is identical for both. Your FastAPI routes and business logic stay the same regardless of whether you choose PydanticAI or LangChain.

WebSocket streaming with full event access

Modern AI applications demand real-time responses. Users should see text appear as it generates, know when the PydanticAI agent calls a tool, and understand what is happening behind the scenes.

Our WebSocket implementation streams every event from the agent to the Next.js frontend

This granularity enables rich user interfaces. The React frontend can show "Agent is calling get_weather…" while the tool executes, display tool arguments and results inline, and stream the final response character by character. Users see exactly what is happening, building trust in the AI system.

The WebSocket connection manager handles lifecycle properly: graceful disconnection, automatic cleanup, and connection state tracking. When clients disconnect mid-response, resources are freed without errors.

Conversation persistence with PostgreSQL/MongoDB

For applications where conversation history matters, we provide full persistence with a three-model schema:

• Conversation → Message → ToolCall

Conversations belong to users (when JWT authentication is enabled) and have titles auto-generated from the first message. Messages track role (user, assistant, system), content, timestamps, and the model that generated them. Tool calls are linked to messages with their arguments, results, and execution status.

The WebSocket handler automatically saves messages to PostgreSQL or MongoDB as they occur. Users can resume conversations by passing a conversation_id — the PydanticAI agent receives the full history and continues seamlessly. The Next.js frontend displays a conversation sidebar for navigation between chats.

Extensible tool system

Every PydanticAI agent includes a base tool for getting the current date and time. Adding custom tools follows a simple pattern: define the tool function with type hints and a docstring, register it with the agent using the @agent.tool decorator and it is made available for the LLM to call.

Tools receive a dependency context object containing the current user, request metadata, and any other request-scoped data. This enables tools like "search my documents" to be aware of user permissions without a global state.

Enterprise features: authentication, observability, background tasks #

A template is only as useful as its production readiness. We included the integrations that enterprise AI applications actually need.

JWT Authentication with Refresh Tokens

The authentication system supports multiple strategies that can be combined:

• JWT + Refresh Tokens is the primary method. Access tokens expire in 30 minutes, refresh tokens last 7 days. The Next.js frontend automatically refreshes tokens before expiry using HTTP-only cookies, avoiding localStorage security vulnerabilities. Token validation happens through FastAPI dependencies, keeping route handlers clean.
• API Key Authentication serves service-to-service communication or simpler integrations. Keys are validated against environment configuration and can coexist with JWT auth.
• OAuth2 with Google provides social login with proper state management and CSRF protection. The flow handles token exchange, user creation for first-time logins, and account linking for existing users.
• Session Management tracks where users are logged in. Users can see their active sessions, login history, and revoke sessions remotely — essential for enterprise security requirements.

Logfire observability from day one

We integrated Logfire throughout the stack because debugging production AI applications is hard. When a user reports "the chatbot gave a weird answer," you need to see exactly what happened.

The FastAPI lifespan handler configures instrumentation for every subsystem: FastAPI requests with full request/response bodies, PostgreSQL queries via asyncpg with SQL and parameters, Redis cache operations, external HTTP calls via HTTPX, and PydanticAI agent reasoning including tool calls and model responses.

Every request gets a unique ID that flows through logs, traces, and error reports. When something fails, you see the complete picture: the user's message, the PydanticAI agent's reasoning, the tool calls, the PostgreSQL queries, and the exact point of failure.

For LangChain users, we configured LangSmith with equivalent instrumentation depth.

Optional Sentry integration catches unhandled exceptions with full context. Prometheus metrics expose request counts, latencies, and custom business metrics for Grafana dashboards and alerting.

Background tasks: Celery, Taskiq, ARQ

Long-running operations should not block FastAPI HTTP requests. We support three background task systems, each with different trade-offs:

• Celery is battle-tested with an extensive ecosystem. It supports scheduled tasks via Celery Beat, task chains, and complex workflows. The generated configuration includes Redis as broker, result backend setup, and example tasks.
• Taskiq is async-native and modern. It integrates naturally with async FastAPI applications and has a lighter footprint than Celery while supporting similar features.
• ARQ is minimal and focused. It uses Redis directly without additional abstractions, perfect for simple use cases where you just need reliable background execution.

All three integrate with the same Redis instance when enabled and include Logfire instrumentation for task tracing. The generator includes example tasks demonstrating common patterns: processing uploads, sending notifications, and scheduled cleanup.

Redis caching and rate limiting

Protection against abuse comes built-in. Rate limiting uses slowapi with configurable requests-per-period limits. Storage backends include in-memory for single instances and Redis for distributed deployments.

Caching with fastapi-cache2 reduces PostgreSQL load for expensive queries. The integration configures Redis as the cache backend with sensible defaults and decorator-based cache control.

SQLAdmin Panel

For applications that need administrative access, SQLAdmin provides a production-ready interface for managing PostgreSQL data. It requires superuser authentication by default and can be restricted to specific environments, typically enabled in development and staging but disabled in production.

The admin panel auto-discovers SQLAlchemy models and provides CRUD operations, filtering, and search out of the box.

Next.js 15 Frontend with React Chat Interface #

Most backend templates include minimal frontend or none at all. We built a complete Next.js application because AI applications need sophisticated user interfaces.

Modern React Stack

The frontend uses Next.js 15 with App Router, React 19 with Server Components, TypeScript in strict mode, and Tailwind CSS v4. Bun serves as the package manager, providing 3x faster installs than npm.

State management combines Zustand for client state (current conversation, UI state) and React Query for server state (conversations list, user data) with automatic caching and revalidation.

AI chat interface with tool visualization

The React chat component is production-ready, not a demo. It handles WebSocket connections with automatic reconnection, streams messages with proper loading states, renders Markdown with syntax highlighting via rehype-highlight, and displays PydanticAI tool calls inline with their arguments and results.

Connection status appears in the UI so users know when they are connected to the WebSocket. Message history persists across page refreshes when PostgreSQL conversation persistence is enabled.

Playwright E2E Testing

The frontend includes both unit tests, with Vitest and Testing Library, and end-to-end tests with Playwright. E2E tests cover critical flows: JWT authentication, sending messages via WebSocket, receiving streamed responses, and conversation management.

Developer experience: Makefile, CLI Commands, AI Assistance #

We obsess over developer experience because we use this template ourselves.

Makefile commands

Every generated project includes a Makefile with commands that eliminate the need to remember tool-specific flags: make install , make run , make test , make lint , make docker-db , make db-migrate , make db-upgrade , make create-admin . One command does what you need.

Django-Style CLI commands

Custom management commands live in app/commands/ and are auto-discovered using Typer. Create a new Python file with a Typer app and it is immediately available through the CLI. Common commands are included: seeding test data into PostgreSQL, cleanup tasks, and examples demonstrating the pattern.

Claude Code and Cursor integration

Every generated project includes CLAUDE.md and AGENTS.md files that help AI coding assistants understand the codebase. These files describe the FastAPI project structure, key conventions (repository pattern, Pydantic schemas), and where to find more information. When you use Claude Code, Cursor, or GitHub Copilot, they understand your project's patterns immediately.

Community validation and quality metrics #

We did not build this template in isolation. It emerged from dozens of production FastAPI + PydanticAI projects and has been validated by the developer community.

Developer response

When we released fastapi-fullstack , the response exceeded our expectations:

"I've just forked it. Still exploring, but it seems magnificent."

"For anyone building with FastAPI, this template is a game-changer — it just cut my AI project setup from months to hours. The CLI sets up a production-ready stack with built-in LLM support, auth, Redis, Docker, and more. I was live in minutes."

"Man! This is amazing. I mean mind bending… Keep up the good work, I'll use it as a reference for my next project."

Quality metrics

The Cookiecutter generator maintains 100% test coverage. We support Python 3.11, 3.12, and 3.13. Development is active with regular releases adding new integrations and improvements

Quick start: install and run in 5 minutes #

Installation takes one command:

pip install fastapi-fullstack Create your project interactively or with direct options:

# Interactive wizard - recommended for first project full-stack-ai-agent-template new # Direct creation with specific options fastapi-fullstack create my_app \\ --database postgresql \\ --auth jwt \\ --frontend nextjs \\ --ai-agent \\ --ai-framework pydantic_ai # Presets for common configurations full-stack-ai-template create my_app --preset ai-agent Roadmap and contribution full-stack-ai-agent-template is under active development. Our roadmap includes more OAuth providers (GitHub, Microsoft, Apple), more AI frameworks (CrewAI, AutoGen integration), more databases (MySQL, CockroachDB), and deployment templates for platforms like Fly.io , Railway, and Render.

We welcome contributions. The project is open source under MIT license and we actively review pull requests.

Build production AI Systems with Vstorm #

We built the full-stack-ai-agent-template because we were tired of solving the same problems over and over again. Now we are sharing it so you can focus on what matters: your unique AI product.

But sometimes you need more than a template. Sometimes you need a team that has built dozens of FastAPI + PydanticAI applications and knows the pitfalls before you hit them.

At Vstorm, we specialize in production AI systems. From manufacturing chatbots to enterprise ML pipelines, we have shipped projects that handle thousands of queries daily. Our team can take you from prototype to production faster than you imagined possible

Book your consultation

Resources #

• GitHub : vstorm-co/full-stack-fastapi-nextjs-llm-template
• PyPI : fastapi-fullstack
• FastAPI Documentation : fastapi.tiangolo.com
• PydanticAI Documentation : ai.pydantic.dev
• Logfire Documentation : https://logfire.pydantic.dev/docs/
• Next.js Documentation : nextjs.org/docs
• Related : pydantic-deep — Our deep agent framework for complex AI workflows

Built with care at Vstorm.co