init
This commit is contained in:
218
README.md
Normal file
218
README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user