b4cddf41ea
- Fork elmeg-demo codebase for multi-band support - Add data importer infrastructure with base class - Create band-specific importers: - phish.py: Phish.net API v5 - grateful_dead.py: Grateful Stats API - setlistfm.py: Dead & Company, Billy Strings (Setlist.fm) - Add spec-kit configuration for Gemini - Update README with supported bands and architecture
118 lines
2.2 KiB
Markdown
118 lines
2.2 KiB
Markdown
# 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.
|