🚀 Key Features

Architecture & Development

Frontend (Next.js)

Backend (Python Firebase Functions)

📋 Prerequisites

🔧 Quick Setup

1. Create Firebase Project

2. Enable Firebase Services

Authentication

Firestore Database

Storage

Functions

3. Get Firebase Configuration

4. Clone and Setup Project

# Clone the repositorygit clone<your-repo-url>cd<project-directory># Install Firebase CLI globallynpm install -g firebase-tools# Login to Firebasefirebase login# Configure Firebase project# Edit .firebaserc and replace with your project ID

🖥️ Frontend Setup (Next.js)

cd front# Install dependenciesyarn install# ornpm install# Create environment filecp .env.example .env.local

Environment Configuration

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key_hereNEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.comNEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-idNEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.comNEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abcdefNEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX

Run Frontend Development Server

yarn dev# ornpm run dev

🐍 Backend Setup (Python Firebase Functions)

Setup Python Environment

cd back# Create and activate virtual environmentpython -m venv venvsource venv/bin/activate# On Windows: venv\Scripts\activate# Install dependenciespip install -r requirements.txt

Configure Service Account

cp .env.example .env# Edit .env and add:# FIREBASE_SERVICE_ACCOUNT_PATH=./your-service-account-key.json# Add any other API keys your project needs

Backend Development Workflow

# Start Firebase emulators (required for testing)firebase emulators:start# In another terminal, run testscd backsource venv/bin/activate# Run all tests with emulators (recommended)python run_tests.py# Run only unit tests (fast, no emulator needed)python run_tests.py --test-type unit --no-emulator# Run only integration testspython run_tests.py --test-type integration# Manual testing with pytestpytest# Ensure emulators are running first

Deploy Functions

# Deploy functions onlyfirebase deploy --only functions# Deploy security rulesfirebase deploy --only firestore:rules,storage:rules# Deploy everythingfirebase deploy

📁 Project Structure

nextjs-firebase-ai-coding-template/├── front/                         # Next.js Frontend│   ├── src/│   │   ├── app/                   # Next.js app router pages│   │   │   ├── layout.tsx         # Root layout│   │   │   ├── page.tsx           # Home page│   │   │   ├── signin/            # Sign in page│   │   │   ├── signup/            # Sign up page│   │   │   └── dashboard/         # Protected dashboard│   │   ├── auth/                  # Authentication logic│   │   │   ├── authContext.ts     # Auth context definition│   │   │   ├── authOperations.ts  # Auth functions│   │   │   ├── AuthProvider.tsx   # Auth context provider│   │   │   └── useAuth.ts         # Auth hook│   │   ├── lib/                   # Firebase services│   │   │   ├── firebase.ts        # Firebase initialization│   │   │   ├── firestore.ts       # Firestore operations│   │   │   ├── functions.ts       # Cloud Functions│   │   │   └── storage.ts         # Storage operations│   │   ├── theme/                 # MUI theme configuration│   │   └── config.ts              # App configuration│   ├── .env.example              # Environment variables template│   ├── package.json│   └── FRONTEND_RULES.md         # Frontend-specific AI rules├── back/                          # Python Firebase Functions Backend│   ├── main.py                    # Firebase function exports│   ├── run_tests.py              # Test runner with emulator management│   ├── requirements.txt           # Python dependencies│   ├── pytest.ini                # Pytest configuration│   ├── .env.example              # Backend environment template│   ├── BACKEND_RULES.md         # Backend-specific AI rules│   ├── ADR.md                    # Architecture Decision Records│   ├── src/│   │   ├── apis/                  # Database interfaces and API clients│   │   │   └── Db.py              # Database singleton│   │   ├── brokers/               # Firebase function handlers│   │   │   ├── callable/          # Client-callable functions│   │   │   ├── https/             # HTTP endpoints│   │   │   └── triggered/         # Event-triggered functions│   │   ├── documents/             # Firestore document classes│   │   │   ├── DocumentBase.py    # Base document class│   │   │   └── [collections]/     # Collection-specific classes│   │   ├── models/                # Data models and types│   │   │   ├── firestore_types.py # Firestore document types│   │   │   ├── function_types.py  # Function request/response types│   │   │   └── util_types.py      # Utility types│   │   ├── services/              # Business logic services│   │   ├── util/                  # Utility functions│   │   └── exceptions/            # Custom exceptions│   └── tests/│       ├── conftest.py            # Pytest fixtures│       ├── integration/           # Integration tests│       └── unit/                  # Unit tests├── tasks/                         # AI Development Templates│   ├── PRD.md                    # Product Requirements Document template│   └── TASK_TEMPLATE.md          # Task breakdown template├── AGENTS.md                     # AI agent instructions├── firebase.json                  # Firebase configuration├── firestore.rules               # Firestore security rules├── storage.rules                 # Storage security rules└── README.md                     # This file

🔐 Security Rules

Firestore Rules

rules_version='2';servicecloud.firestore{match/databases/{database}/documents{// Allow users to read/write their own documentsmatch/users/{userId}{      allowread,write:ifrequest.auth!=null&&request.auth.uid==userId;}}}

Storage Rules

rules_version='2';servicefirebase.storage{match/b/{bucket}/o{match/users/{userId}/{allPaths=**}{      allowread,write:ifrequest.auth!=null&&request.auth.uid==userId;}}}

🤖 AI-Assisted Development Workflow

1. Project Scoping (GPT-4o or similar)

# Generate PRD from requirements# Use tasks/PRD.md template# Ask AI to interview you until it can fill the PRD# Break down into tasks# Use tasks/TASK_TEMPLATE.md# Have AI create specific, actionable tasks with dependencies

2. Parallel Agent Development

# Agent 1: Frontend auth@AGENTS.md @FRONTEND_RULES.md implement [task1.md]# Agent 2: Backend API@AGENTS.md @BACKEND_RULES.md implement [task2.md]# Agent 3: Database models@AGENTS.md @BACKEND_RULES.md implement [task3.md]# Agent 4: Integration tests@AGENTS.md implement integration testsfor [feature]

3. Testing Workflow

# Backend: Always write integration tests firstcd backsource venv/bin/activatepython run_tests.py# Tests with real APIs# Frontend: Test with emulatorsfirebase emulators:startcd front&& yarn dev

4. Documentation

# Tell agent to document decisions"Document the key architectural decisions in back/ADR.md"

💻 Traditional Development Workflow

Frontend Development

cd frontyarn dev# Start development serveryarn build# Build for productionyarn lint# Run linting

Backend Development

cd backsource venv/bin/activate# Run testspython run_tests.py# All tests with emulatorspython run_tests.py --test-type unit# Unit tests onlypython run_tests.py --test-type integration# Integration tests only

Full-Stack Development

📚 Usage Examples

Frontend Authentication

import{useAuth}from"@/auth/useAuth";import{authOperations}from"@/auth/authOperations";// Using the auth hookfunctionMyComponent(){const{ user, loading, isAuthenticated}=useAuth();if(loading)return<div>Loading...</div>;if(!isAuthenticated)return<div>Pleasesignin</div>;return<div>Welcome,{user.email}!</div>;}// Auth operationsawaitauthOperations.signUp(email,password,displayName);awaitauthOperations.signIn(email,password);awaitauthOperations.signInWithGoogle();awaitauthOperations.signOut();

Frontend Firestore Operations

import{userOperations}from"@/lib/firestore";// Create user documentawaituserOperations.create(uid,{ displayName, email});// Get user by IDconstuser=awaituserOperations.getById(uid);// Update userawaituserOperations.update(uid,{displayName:"New Name"});

Backend Callable Functions

# src/brokers/callable/example_callable.pyfromfirebase_functionsimporthttps_fn,optionsfromsrc.apis.DbimportDbfromsrc.util.db_auth_wrapperimportdb_auth_wrapper@https_fn.on_call(cors=options.CorsOptions(cors_origins=["*"]),ingress=options.IngressSetting.ALLOW_ALL,)defexample_callable(req:https_fn.CallableRequest):uid=db_auth_wrapper(req)# Implementation

Backend Document Classes

# src/documents/examples/Example.pyfromsrc.documents.DocumentBaseimportDocumentBasefromsrc.apis.DbimportDbfromsrc.models.firestore_typesimportExampleDocclassExample(DocumentBase[ExampleDoc]):pydantic_model=ExampleDocdef__init__(self,id:str,doc:Optional[dict]=None):self._db=Db.get_instance()self.collection_ref=self.db.collections["examples"]super().__init__(id,doc)@propertydefdb(self)->Db:ifself._dbisNone:self._db=Db.get_instance()returnself._db

🚀 Deployment

Frontend Deployment (Vercel)

Backend Deployment (Firebase Functions)

cd backfirebase deploy --only functions

Production Configuration

defis_prod_environment(self)->bool:returnself.project_idin ["your-prod-project-id"]defis_dev_environment(self)->bool:returnself.project_idin ["your-dev-project-id"]

# Review and customize rules firstcat firestore.rulescat storage.rules# Deploy rulesfirebase deploy --only firestore:rules,storage:rules

🧪 Testing Strategy

Testing Philosophy

AI Testing Guidelines

# Always tell AI to:1. Write integration tests with real data2. Run tests and verify they pass3. Test with actual files/APIs, not mocks4. Show you where to find generated outputs

Example Test Pattern

deftest_feature_integration(self,firebase_emulator,setup):# Arrange - Prepare test datatest_data= {"field":"value"}# Act - Call real Firebase Functionresponse=requests.post(f"{firebase_emulator['base_url']}/function_name",json={"data":test_data},headers={"User-Id":setup.user_id}    )# Assert - Verify responseassertresponse.status_code==200result=response.json()["result"]# Assert - Verify database statedoc=DocumentClass(result["docId"])assertdoc.existsassertdoc.data.field=="value"

🎯 Architecture Principles

Event-Driven Broker Architecture

Backend Principles

Type Safety

AI Development Principles

📜 Available Commands

Frontend Commands

cd frontyarn dev# Start development serveryarn build# Build for productionyarn start# Start production serveryarn lint# Run ESLintyarn type-check# Run TypeScript checks

Backend Commands

cd backpython run_tests.py# Run all tests with emulatorspython run_tests.py --test-type unit# Unit tests onlypython run_tests.py --test-type integration# Integration testspytest --cov=src# Run with coverage report

Firebase Commands

firebase emulators:start# Start local emulatorsfirebase deploy# Deploy everythingfirebase deploy --only functions# Deploy functions onlyfirebase deploy --only hosting# Deploy frontend onlyfirebase deploy --only firestore:rules# Deploy Firestore rules

🔧 Environment Variables

Frontend (front/.env.local)

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_keyNEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domainNEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_idNEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucketNEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_idNEXT_PUBLIC_FIREBASE_APP_ID=your_app_idNEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

Environment Variables

🚀 Quick Start Checklist

📚 Resources

🆘 Support