hack-nation/README.md

# 🚀 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

```bash
# 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

```bash
# 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

```bash
# 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](https://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](https://platform.openai.com) or [Anthropic](https://anthropic.com)
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

```bash
# 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:

```sql
-- 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](https://vercel.com)
3. Add environment variables
4. Deploy!

### Backend (Railway/Render)

1. Push to GitHub
2. Import in [Railway](https://railway.app) or [Render](https://render.com)
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](https://nextjs.org/docs)
- [FastAPI Docs](https://fastapi.tiangolo.com)
- [Supabase Docs](https://supabase.com/docs)
- [Shadcn/ui Components](https://ui.shadcn.com)
- [OpenAI API](https://platform.openai.com/docs)

---

Built for **Hack Nation 2026** 🏆 template