# User Guide

## Getting Started

This guide will help you get started with the application.

## Installation

### Prerequisites

Before you begin, ensure you have the following installed:

- Docker and Docker Compose
- Python 3.11+ (for local backend development)
- Node.js 20 LTS (for local frontend development)
- uv (Python package manager)

### Quick Start with Docker

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd <project-name>
   ```

2. Start all services:
   ```bash
   docker compose -f deploy/compose.yml up
   ```

3. Access the application:
   - Frontend: http://localhost:3000
   - Backend API: http://localhost:8000
   - API Documentation: http://localhost:8000/docs

## Local Development

### Backend Development

1. Navigate to backend directory:
   ```bash
   cd backend
   ```

2. Copy environment file:
   ```bash
   cp .env.example .env
   ```

3. Install dependencies:
   ```bash
   uv sync
   ```

4. Start the development server:
   ```bash
   uv run uvicorn app.main:app --reload
   ```

Or use the convenience script:
```bash
bash scripts/dev/start-backend.sh
```

### Frontend Development

1. Navigate to frontend directory:
   ```bash
   cd frontend
   ```

2. Copy environment file:
   ```bash
   cp .env.example .env
   ```

3. Install dependencies:
   ```bash
   npm install
   ```

4. Start the development server:
   ```bash
   npm start
   ```

Or use the convenience script:
```bash
bash scripts/dev/start-frontend.sh
```

## Testing

### Backend Tests

```bash
cd backend
uv run pytest --cov=app
```

### Frontend Tests

```bash
cd frontend
npm test
```

## Code Quality

### Linting

```bash
# Backend
bash scripts/utils/lint-backend.sh

# Frontend
bash scripts/utils/lint-frontend.sh
```

### Formatting

```bash
bash scripts/utils/format-all.sh
```

## Common Tasks

### Adding a New API Endpoint

1. Create endpoint in `backend/app/api/`
2. Add business logic in `backend/app/services/`
3. Define schemas in `backend/app/schemas/`
4. Write tests in `backend/tests/`

### Adding a New Frontend Component

1. Create component in `frontend/src/components/`
2. Add styles in `frontend/src/styles/`
3. Write tests in `frontend/tests/components/`

### Database Migrations

(Add database migration instructions when implemented)

## Troubleshooting

### Port Already in Use

If you get a "port already in use" error:

```bash
# Find process using the port
lsof -i :8000  # or :3000 for frontend

# Kill the process
kill -9 <PID>
```

### Docker Issues

```bash
# Clean up Docker resources
docker compose -f deploy/compose.yml down
docker system prune -a
```

### Dependency Issues

```bash
# Backend
cd backend
rm -rf .venv
uv sync

# Frontend
cd frontend
rm -rf node_modules package-lock.json
npm install
```

## Support

For issues and questions:
- Check the documentation in `/docs`
- Review the API documentation at http://localhost:8000/docs
- Open an issue in the repository