Modern AI Stack Template

A powerful template for building AI-powered applications with Next.js, FastAPI, PostgreSQL, and OpenAI.

🚀 Features

Frontend

• Next.js 14.x with TypeScript
• Tailwind CSS + ShadcN UI for beautiful, responsive UI
• React Query for efficient data fetching
• Zustand for state management
• NextAuth.js for authentication

Backend

• FastAPI (Python 3.11+) for high-performance API
• PostgreSQL + pgvector for vector storage
• SQLAlchemy ORM for database operations
• LangChain for AI orchestration

AI Integration

• OpenAI API integration
• Vector embeddings with pgvector
• RAG (Retrieval Augmented Generation)

DevOps

• Docker for containerization
• GitHub Actions for CI/CD
• AWS Lambda deployment ready
• Vercel deployment ready

📋 Getting Started

Prerequisites

• Node.js 18+
• Python 3.11+
• Docker and Docker Compose
• PostgreSQL 14+

Quick Setup with Root Scripts

This project includes root-level scripts to simplify installation and running both frontend and backend components:

# Install all dependencies (both frontend and backend)
npm run install:all

# Start both frontend and backend in development mode
npm run dev

# Start both services in production mode
npm run start

# Use Docker for development (recommended)
npm run docker:dev

Docker Development (Recommended)

The easiest way to get started is using Docker:

# Start the complete development environment
npm run docker:dev

# Access the application at http://localhost:3000
# The API is available at http://localhost:8000

This will start:

• PostgreSQL database with pgvector extension
• FastAPI backend with hot reloading
• Next.js frontend with hot reloading

All services are configured to work together, and your local code changes will be reflected immediately.

Manual Installation

1. Clone the repository:

git clone https://github.com/rikudi/next-fastAPI-postgres.git
cd next-fastAPI-postgres

2. Set up the backend:

cd backend
cp .env.example .env  # Configure your environment variables
docker-compose up -d postgres  # Start PostgreSQL with pgvector
pip install -r requirements.txt

3. Set up the frontend:

cd frontend
cp .env.example .env  # Configure your environment variables
npm install

Running the Application

Using Root Scripts

# From the root directory
npm run dev          # Run both frontend and backend in development mode
npm run dev:frontend # Run only frontend
npm run dev:backend  # Run only backend

Manual Running

1. Start the backend:

cd backend
uvicorn app.main:app --reload

2. Start the frontend:

cd frontend
npm run dev

3. Open your browser and navigate to http://localhost:3000

🛠️ Available Root Scripts

Command	Description
npm run install:all	Install all dependencies for both frontend and backend
npm run install:frontend	Install only frontend dependencies
npm run install:backend	Install only backend dependencies
npm run dev	Run both frontend and backend in development mode
npm run dev:frontend	Run only frontend in development mode
npm run dev:backend	Run only backend in development mode
npm run build:frontend	Build the frontend for production
npm run start	Run both frontend and backend in production mode
npm run start:frontend	Run only frontend in production mode
npm run start:backend	Run only backend in production mode
npm run docker:up	Start all services with Docker Compose
npm run docker:down	Stop all Docker Compose services
npm run docker:dev	Start development environment with Docker Compose
npm run docker:dev:down	Stop development Docker Compose services

🏗️ Project Structure

├── backend/                # FastAPI backend
│   ├── app/                # Application code
│   │   ├── api/            # API endpoints
│   │   ├── core/           # Core functionality
│   │   ├── db/             # Database models
│   │   └── services/       # Business logic
│   ├── alembic/            # Database migrations
│   └── tests/              # Backend tests
│
├── frontend/               # Next.js frontend
│   ├── app/                # App router pages
│   ├── components/         # React components
│   ├── lib/                # Utilities and hooks
│   └── public/             # Static assets
│
└── docker-compose.yml      # Docker configuration

🧠 AI Features

• Document Q&A: Upload documents and ask questions about them
• Semantic Search: Search through documents using natural language
• AI Chat: Chat with an AI assistant that has context from your documents

🛠️ Development

Backend Development

cd backend
python -m pytest  # Run tests

Frontend Development

cd frontend
npm run lint  # Run ESLint
npm run build  # Build for production

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Next.js
• FastAPI
• PostgreSQL
• OpenAI
• LangChain
• shadcn/ui

---

Created by Rikudi