fediversion/docs/DEVELOPER.md

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/:

   cd backend
   

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run Migrations:

   alembic upgrade head
   

5. Seed Data (Optional):

   python seed.py
   

6. Start Server:

   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/:

   cd frontend
   

2. Install dependencies:

   npm install
   

3. Start Dev Server:

   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.