219 lines
5.5 KiB
Markdown
219 lines
5.5 KiB
Markdown
# Paragliding Weather Dashboard
|
|
|
|
Real-time paragliding weather conditions and forecasting application.
|
|
|
|
## Features
|
|
|
|
- 🌤️ Real-time weather data from Open-Meteo
|
|
- 🪂 Paragliding-specific condition assessment
|
|
- 📊 Historical weather data tracking
|
|
- 🎯 Customizable safety thresholds
|
|
- ⚡ Fast API with caching
|
|
- 🔄 Automatic weather data updates
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Go 1.24, Chi router, PostgreSQL
|
|
- **Frontend**: Next.js 14, React 18, TailwindCSS, Recharts
|
|
- **Database**: PostgreSQL 16
|
|
- **Deployment**: Docker/Podman, Kubernetes
|
|
|
|
## Quick Start
|
|
|
|
### Local Development (Fastest)
|
|
|
|
Run only PostgreSQL in a container, everything else natively:
|
|
|
|
```bash
|
|
# One command - setup AND start everything!
|
|
./dev.sh --start
|
|
|
|
# Or setup only, then start manually:
|
|
./dev.sh
|
|
make run-backend # Terminal 1
|
|
make run-frontend # Terminal 2
|
|
```
|
|
|
|
**That's it!** The `--start` flag sets up PostgreSQL, creates config files, runs migrations, AND starts both backend and frontend in the background.
|
|
|
|
**Why local development?**
|
|
- ✨ Faster hot-reload and rebuild times
|
|
- 🔧 Better debugging experience
|
|
- 📦 Smaller resource footprint
|
|
- 🚀 Quicker iteration cycles
|
|
|
|
See [DEV_SETUP.md](./DEV_SETUP.md) for detailed local development guide.
|
|
|
|
### Full Container Development
|
|
|
|
Run everything in containers:
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
Access at:
|
|
- Frontend: http://localhost:3000
|
|
- Backend API: http://localhost:8080/api/v1
|
|
|
|
## Available Make Commands
|
|
|
|
### Local Development
|
|
- `./dev.sh` - **Recommended**: Idempotent setup script
|
|
- `make dev-local` - Setup local development (runs dev.sh)
|
|
- `make dev-db` - Start PostgreSQL only
|
|
- `make dev-db-down` - Stop PostgreSQL
|
|
- `make run-backend` - Run backend locally
|
|
- `make run-frontend` - Run frontend locally
|
|
|
|
### Container Development
|
|
- `make dev` - Start all services in containers
|
|
- `make dev-down` - Stop all containers
|
|
- `make dev-logs` - View backend logs
|
|
- `make dev-logs-frontend` - View frontend logs
|
|
- `make dev-logs-postgres` - View PostgreSQL logs
|
|
|
|
### Database
|
|
- `make migrate-up` - Run migrations
|
|
- `make migrate-down` - Rollback last migration
|
|
- `make migrate-create name=<name>` - Create new migration
|
|
|
|
### Testing
|
|
- `make test` - Run all tests
|
|
- `make test-backend` - Run backend tests only
|
|
- `make test-frontend` - Run frontend tests only
|
|
|
|
### Build
|
|
- `make build` - Build backend and frontend
|
|
- `make build-backend` - Build backend only
|
|
- `make build-frontend` - Build frontend only
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /api/v1/health` - Health check
|
|
- `GET /api/v1/weather/current` - Current conditions
|
|
- `GET /api/v1/weather/forecast` - Weather forecast
|
|
- `GET /api/v1/weather/historical?date=YYYY-MM-DD` - Historical data
|
|
- `POST /api/v1/assess` - Assess conditions with custom thresholds
|
|
|
|
## Configuration
|
|
|
|
### Backend Environment Variables
|
|
|
|
See `backend/.env.example` for all configuration options:
|
|
|
|
- `DATABASE_URL` - PostgreSQL connection string
|
|
- `PORT` - Server port (default: 8080)
|
|
- `LOCATION_LAT` - Latitude for weather data
|
|
- `LOCATION_LON` - Longitude for weather data
|
|
- `LOCATION_NAME` - Location display name
|
|
- `TIMEZONE` - Timezone for weather data
|
|
- `FETCH_INTERVAL` - How often to fetch weather (default: 15m)
|
|
- `CACHE_TTL` - API response cache duration (default: 10m)
|
|
|
|
### Frontend Environment Variables
|
|
|
|
See `frontend/.env.local.example`:
|
|
|
|
- `NEXT_PUBLIC_API_URL` - Backend API URL
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── backend/ # Go backend
|
|
│ ├── cmd/api/ # Application entry point
|
|
│ ├── internal/ # Internal packages
|
|
│ │ ├── cache/ # Caching layer
|
|
│ │ ├── client/ # External API clients
|
|
│ │ ├── config/ # Configuration
|
|
│ │ ├── model/ # Data models
|
|
│ │ ├── repository/ # Database layer
|
|
│ │ ├── server/ # HTTP server
|
|
│ │ └── service/ # Business logic
|
|
│ └── migrations/ # Database migrations
|
|
├── frontend/ # Next.js frontend
|
|
│ ├── app/ # Next.js app directory
|
|
│ ├── components/ # React components
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── lib/ # Utilities
|
|
│ └── store/ # State management
|
|
├── docker-compose.yml # Full stack containers
|
|
├── docker-compose.dev.yml # PostgreSQL only
|
|
├── dev.sh # Idempotent dev setup script
|
|
├── Makefile # Development commands
|
|
└── DEV_SETUP.md # Detailed dev guide
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Initial Setup
|
|
```bash
|
|
# 1. Clone the repository
|
|
git clone <repo-url>
|
|
cd paragliding
|
|
|
|
# 2. Run setup script
|
|
./dev.sh
|
|
|
|
# 3. Start services (in separate terminals)
|
|
make run-backend
|
|
make run-frontend
|
|
```
|
|
|
|
### Daily Development
|
|
```bash
|
|
# Start PostgreSQL (if not running)
|
|
make dev-db
|
|
|
|
# Start backend
|
|
make run-backend
|
|
|
|
# Start frontend
|
|
make run-frontend
|
|
```
|
|
|
|
### Making Changes
|
|
|
|
- **Backend**: Changes auto-reload with Air (if installed) or restart manually
|
|
- **Frontend**: Changes auto-reload with Next.js Fast Refresh
|
|
- **Database**: Create migrations with `make migrate-create name=<name>`
|
|
|
|
## Deployment
|
|
|
|
### Docker/Podman
|
|
|
|
```bash
|
|
# Build and start all services
|
|
docker-compose up -d
|
|
|
|
# Or with podman
|
|
podman-compose up -d
|
|
```
|
|
|
|
### Kubernetes
|
|
|
|
```bash
|
|
# Apply configurations
|
|
kubectl apply -f k8s.yaml
|
|
|
|
# Check status
|
|
kubectl get pods
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests: `make test`
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
ISC
|
|
|
|
## Support
|
|
|
|
For issues and questions, please open a GitHub issue.
|