# TipSharks Monorepo Structure

This repository uses a monorepo structure to organize the TipSharks application.

## Directory Structure

```
tipsharks/
├── apps/
│   ├── backend/              # Python FastAPI backend
│   │   ├── api/              # REST API server
│   │   ├── worker/           # CLI tools for data ingestion
│   │   └── web/              # Simple web UI (temporary)
│   └── frontend/             # Future React/SvelteKit frontend
│
├── packages/
│   ├── core/                 # Core Python business logic
│   │   ├── common/           # Settings, logging, utilities
│   │   ├── ratings/          # Rating engine algorithms
│   │   └── storage/          # Database models & repositories
│   └── hrnz_client/          # HRNZ API integration
│
├── infrastructure/
│   ├── docker/               # Dockerfiles for all services
│   ├── alembic/              # Database migrations
│   └── scripts/              # Deployment scripts
│
├── docs/                     # Documentation
├── tests/                    # Test files
├── pyproject.toml            # Python package configuration
└── docker-compose.yml        # Docker orchestration
```

## Benefits

- **Clear Separation**: Backend and frontend are independently versioned
- **Shared Packages**: Core logic is reusable across apps
- **Scalable**: Easy to add new apps (mobile, admin, etc.)
- **Better DX**: Each app has its own dependencies and configuration
- **Future-Ready**: Prepared for TypeScript frontend with shared types

## Working with the Monorepo

### Backend Development

```bash
# Run API server
docker compose up api

# Run worker commands
docker compose run --rm worker python -m apps.backend.worker.cli --help

# Run tests
pytest
```

### Future Frontend Development

When adding React/SvelteKit frontend:

1. Create `apps/frontend/` directory
2. Add `package.json` with workspace configuration
3. Share types between backend and frontend via `packages/types/`

## Import Paths

- Backend apps: `from apps.backend.api import ...`
- Core packages: `from packages.core.ratings import ...`
- HRNZ client: `from packages.hrnz_client import ...`

## Adding New Apps

1. Create directory under `apps/`
2. Add to pyproject.toml packages list
3. Update docker-compose.yml if needed