# Elmeg Developer Guide

## Tech Stack

- **Backend**: Python (FastAPI), SQLModel, Alembic, SQLite.
- **Frontend**: TypeScript (Next.js 15), Tailwind CSS 4, Shadcn UI.
- **Containerization**: Docker.

## Getting Started

### Prerequisites

- Python 3.10+
- Node.js 18+
- Docker (optional but recommended)

### Backend Setup

1. Navigate to `backend/`:

   ```bash
   cd backend
   ```

2. Create virtual environment:

   ```bash
   python -m venv venv
   source venv/bin/activate
   ```

3. Install dependencies:

   ```bash
   pip install -r requirements.txt
   ```

4. Run Migrations:

   ```bash
   alembic upgrade head
   ```

5. Seed Data (Optional):

   ```bash
   python seed.py
   ```

6. Start Server:

   ```bash
   uvicorn main:app --reload
   ```

   API will be available at `http://localhost:8000`.
   Swagger Docs at `http://localhost:8000/docs`.

### Frontend Setup

1. Navigate to `frontend/`:

   ```bash
   cd frontend
   ```

2. Install dependencies:

   ```bash
   npm install
   ```

3. Start Dev Server:

   ```bash
   npm run dev
   ```

   App will be available at `http://localhost:3000`.

## Project Structure

### Backend (`/backend`)

- `main.py`: Entry point.
- `models.py`: Database models (SQLModel).
- `routers/`: API route handlers (split by feature).
- `services/`: Business logic (e.g., stats calculation).
- `alembic/`: Database migrations.

### Frontend (`/frontend`)

- `app/`: Next.js App Router pages.
- `components/`: Reusable UI components.
  - `ui/`: Shadcn UI primitives.
  - `social/`, `shows/`, `profile/`: Feature-specific components.
- `contexts/`: React Contexts (e.g., Preferences).
- `lib/`: Utilities.

## Key Workflows

### Adding a New Model

1. Define model in `backend/models.py`.
2. Generate migration: `alembic revision --autogenerate -m "add model"`.
3. Apply migration: `alembic upgrade head`.
4. Create CRUD router in `backend/routers/`.

### Adding a New Page

1. Create folder in `frontend/app/` (e.g., `my-feature`).
2. Add `page.tsx`.
3. Fetch data from API (use `fetch` in Server Components or `useEffect` in Client Components).

## Testing

- Currently manual testing via Swagger UI and Frontend.
- Future: Add `pytest` for backend and `jest`/`playwright` for frontend.