template

2026-02-03 21:58:25 +01:00
parent 3019bcaf1a
commit 959dad3fec
14 changed files with 1477 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,268 @@
-# hack-nation template
+# 🚀 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