🚀 Hack Nation 2026 - Full-Stack Template

A comprehensive hackathon template with Next.js, FastAPI, Supabase, and AI integration.

📁 Project Structure

hack-nation/
├── frontend/                 # Next.js 14 + React
│   ├── src/
│   │   ├── app/             # App Router pages
│   │   │   ├── layout.tsx   # Root layout
│   │   │   ├── page.tsx     # Home page
│   │   │   ├── login/       # Auth page
│   │   │   ├── dashboard/   # Protected page
│   │   │   └── demo/        # Feature demos
│   │   ├── components/      # React components
│   │   │   ├── ui/          # Shadcn/ui components
│   │   │   └── ...          # Custom components
│   │   └── lib/             # Utilities & services
│   │       ├── supabase/    # Supabase client & provider
│   │       └── api.ts       # Backend API client
│   └── package.json
│
├── backend/                  # FastAPI (Python)
│   ├── main.py              # FastAPI app entry
│   ├── config.py            # Environment configuration
│   ├── routers/             # API route handlers
│   │   ├── ai.py            # AI generation endpoints
│   │   ├── projects.py      # CRUD example
│   │   └── health.py        # Health checks
│   └── services/            # Business logic
│       ├── ai_service.py    # AI provider integration
│       └── database.py      # Supabase helpers
│
└── README.md

🛠 Tech Stack

Layer	Technology	Why?
Frontend	Next.js 14	React framework with App Router, SSR, and great DX
UI Components	Shadcn/ui	Beautiful, accessible, customizable components
Styling	Tailwind CSS	Utility-first CSS, rapid development
Backend	FastAPI	Fast Python API, auto docs, async support
Database	Supabase	Postgres + Auth + Realtime, generous free tier
AI	OpenAI/Anthropic	GPT-4 or Claude for AI features

🚀 Quick Start

1. Clone & Install

# Clone the repo (or use this template)
cd hack-nation

# Install frontend dependencies
cd frontend
npm install

# Install backend dependencies
cd ../backend
pip install -r requirements.txt

2. Configure Environment

# Frontend
cd frontend
cp .env.local.example .env.local
# Edit .env.local with your Supabase keys

# Backend
cd ../backend
cp .env.example .env
# Edit .env with your API keys

3. Run Development Servers

# Terminal 1: Frontend (localhost:3000)
cd frontend
npm run dev

# Terminal 2: Backend (localhost:8000)
cd backend
python run.py

4. View Your App

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

⚙️ Configuration

Supabase Setup

1. Create a project at supabase.com
2. Go to Settings → API
3. Copy the URL and anon key to frontend .env.local
4. Copy the URL and service role key to backend .env

AI Setup

1. Get an API key from OpenAI or Anthropic
2. Add to backend .env:

   OPENAI_API_KEY=sk-your-key-here
   AI_PROVIDER=openai
   AI_MODEL=gpt-3.5-turbo
   

📚 Key Concepts

Frontend Architecture

┌─────────────────────────────────────────┐
│              layout.tsx                  │
│  ┌────────────────────────────────────┐ │
│  │           Providers                 │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │       Navigation             │  │ │
│  │  ├──────────────────────────────┤  │ │
│  │  │       page.tsx               │  │ │
│  │  │   (Route-specific content)   │  │ │
│  │  └──────────────────────────────┘  │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘

• layout.tsx: Wraps all pages, contains providers
• page.tsx: Individual page content
• Providers: Context for auth, theme, etc.

Backend Architecture

Request → Router → Service → Response
           │          │
           │          └── AI Service / Database
           │
           └── Validates input with Pydantic

• Routers: Handle HTTP requests, validate input
• Services: Business logic, external integrations
• Config: All settings from environment variables

Data Flow

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Frontend │────▶│ Backend  │────▶│   AI     │
│ (Next.js)│◀────│ (FastAPI)│◀────│ Provider │
└──────────┘     └──────────┘     └──────────┘
      │                │
      │                │
      ▼                ▼
┌─────────────────────────────────────────┐
│              Supabase                    │
│  (Database, Auth, Realtime, Storage)    │
└─────────────────────────────────────────┘

🎨 Adding Shadcn/ui Components

# Initialize shadcn (first time only)
cd frontend
npx shadcn-ui@latest init

# Add components as needed
npx shadcn-ui@latest add button
npx shadcn-ui@latest add card
npx shadcn-ui@latest add dialog
npx shadcn-ui@latest add dropdown-menu

🔌 API Endpoints

AI Endpoints

Method	Endpoint	Description
POST	/api/ai/generate	Generate text from prompt
POST	/api/ai/chat	Chat with message history
POST	/api/ai/stream	Stream AI response
GET	/api/ai/models	List available models

Project Endpoints (Example CRUD)

Method	Endpoint	Description
GET	/api/projects	List all projects
POST	/api/projects	Create project
GET	/api/projects/:id	Get project
PATCH	/api/projects/:id	Update project
DELETE	/api/projects/:id	Delete project

🗄 Database Schema (Supabase)

Run these SQL commands in Supabase SQL Editor:

-- Projects table
CREATE TABLE projects (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT DEFAULT '',
  user_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

-- Users can only access their own projects
CREATE POLICY "Users can CRUD own projects"
  ON projects FOR ALL
  USING (auth.uid() = user_id);

🚢 Deployment

Frontend (Vercel)

1. Push to GitHub
2. Import project in Vercel
3. Add environment variables
4. Deploy!

Backend (Railway/Render)

1. Push to GitHub
2. Import in Railway or Render
3. Set environment variables
4. Deploy!

Supabase

Already hosted! Just keep your project running.

💡 Hackathon Tips

1. Start with the AI demo - It already works!
2. Use Shadcn/ui components - Don't build from scratch
3. Leverage Supabase - Auth and DB are ready
4. Keep it simple - One cool feature > many half-done ones
5. Test the happy path - Edge cases can wait

📖 Learn More

• Next.js Docs
• FastAPI Docs
• Supabase Docs
• Shadcn/ui Components
• OpenAI API

---

Built for Hack Nation 2026 🏆 template