BESSER-FOR-CLIMA

A comprehensive climate data platform for the ClimaBorough project, enabling cities to visualize, analyze, and manage climate-related data through customizable dashboards.

📋 Table of Contents

• Introduction
• Architecture
• Prerequisites
• Installation
  • Backend Setup
  • Frontend Setup
  • Chat Bot Setup
• Docker Deployment
• Database Management
• Configuration
• Development
• API Documentation
• Contributing
• License

🌍 Introduction

BESSER-FOR-CLIMA is a model-driven platform that provides a low-code/no-code dashboard solution for climate data visualization and management. As part of the EU-funded ClimaBorough project, the platform enables:

• Dynamic Dashboard Creation: Build customizable dashboards with drag-and-drop widgets
• Multi-City Support: Manage data for multiple cities with role-based access control
• Rich Visualizations: Line charts, bar charts, pie charts, stat widgets, tables, timelines, and maps
• Real-time Data: WebSocket-based live updates and chat assistant integration
• RESTful API: Comprehensive FastAPI backend with automatic OpenAPI documentation
• Code Generation: Automated generation of models, schemas, and API endpoints from domain models

🏗️ Architecture

The platform consists of three main components:

BESSER-FOR-CLIMA/
├── backend/           # FastAPI application with PostgreSQL
├── frontend/          # React + TypeScript + Vite SPA
└── climasolutionsbot/ # Python-based chat assistant

Technology Stack:

• Backend: Python 3.11, FastAPI, SQLAlchemy, Pydantic, PostgreSQL
• Frontend: React 18, TypeScript, Vite, TailwindCSS, shadcn/ui
• Authentication: Keycloak (OpenID Connect)
• Deployment: Docker, Kubernetes, nginx

⚙️ Prerequisites

• Python 3.11.1 or higher
• Node.js 22.x or higher
• Docker and Docker Compose
• PostgreSQL 14+ (for local development without Docker)
• Git

🚀 Installation

Backend Setup

1. Create Virtual Environment

cd backend
python -m venv besser_venv

# Windows
besser_venv\Scripts\activate

# Linux/macOS
source besser_venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Generate Backend Code

The platform uses model-driven engineering to generate code from domain models:

python generate.py

This generates:

• SQLAlchemy ORM models
• FastAPI route handlers
• Pydantic schemas for request/response validation
• Repository pattern implementations

4. Configure Environment

Create a .env file in backend/src/:

DATABASE_URL=postgresql://postgres:password@localhost:5432/climaborough
SECRET_KEY=your-secret-key-here
KEYCLOAK_SERVER_URL=https://auth.climaplatform.eu
KEYCLOAK_REALM=climaborough
KEYCLOAK_CLIENT_ID=climaborough-backend

5. Run Database Migrations

cd src
python init_db.py

6. Start the Backend

cd src
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Access the API at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Frontend Setup

1. Install Dependencies

cd frontend
npm install

2. Configure Environment

Create a .env file in frontend/:

VITE_API_URL=http://localhost:8000
VITE_WEBSOCKET_URL=ws://localhost:8765
VITE_KEYCLOAK_URL=https://auth.climaplatform.eu
VITE_KEYCLOAK_REALM=climaborough
VITE_KEYCLOAK_CLIENT_ID=climaborough-frontend

3. Start Development Server

npm run dev

The application will be available at http://localhost:5173

4. Build for Production

npm run build

The optimized build will be in the dist/ folder.

Chat Bot Setup

1. Navigate to Bot Directory

cd climasolutionsbot

2. Install Dependencies

python -m venv besser_venv
besser_venv\Scripts\activate  # Windows
pip install -r requirements.txt

3. Configure Bot

Edit config.ini with your settings:

[API]
base_url = http://localhost:8000

[WebSocket]
host = 0.0.0.0
port = 8765

4. Run the Bot

python climabot.py

🐳 Docker Deployment

Backend

Local Development

cd backend/docker
docker-compose -f docker-compose.local.yaml up -d

This starts:

• PostgreSQL database on port 5432
• PgAdmin on http://localhost:80
• Backend API on http://localhost:8000

Production Deployment

cd backend/docker
docker-compose -f docker-compose.remote.yaml build
docker-compose -f docker-compose.remote.yaml up -d

Frontend

Build Docker Image

cd frontend
docker build -t climaborough-frontend .

Run Container

docker run -p 80:80 \
  -e API_URL=https://api.climaplatform.eu \
  -e WEBSOCKET_URL=wss://bot.climaplatform.eu \
  climaborough-frontend

Push to Registry

docker tag climaborough-frontend artefacts.list.lu/climaborough/frontend:latest
docker push artefacts.list.lu/climaborough/frontend:latest

💾 Database Management

Create Backup

cd backend/docker
docker exec climaborough_postgres_remote pg_dump -U postgres climaborough > backup_$(date +%Y%m%d).sql

Restore Backup

docker exec -i climaborough_postgres_remote psql -U postgres climaborough < backup.sql

Run Migrations

# Apply StatChart schema updates
docker exec -i climaborough_postgres_remote psql -U postgres climaborough < add_statchart_columns.sql

See Remote-Database-Backup-Guide.md for detailed instructions.

⚙️ Configuration

Backend Configuration

Key configuration files:

• backend/src/app/core/config.py - Application settings
• backend/src/app/core/security.py - Authentication configuration
• backend/plantuml/buml_model.py - Domain model definitions

Frontend Configuration

• frontend/vite.config.ts - Build configuration
• frontend/src/config/env.js - Runtime environment variables
• frontend/tailwind.config.js - Styling configuration

Environment Variables

Backend:

• DATABASE_URL - PostgreSQL connection string
• SECRET_KEY - JWT signing key
• KEYCLOAK_SERVER_URL - Authentication server
• CORS_ORIGINS - Allowed CORS origins

Frontend:

• VITE_API_URL - Backend API endpoint
• VITE_WEBSOCKET_URL - WebSocket server
• VITE_KEYCLOAK_URL - Keycloak server
• VITE_KEYCLOAK_REALM - Keycloak realm
• VITE_KEYCLOAK_CLIENT_ID - OAuth client ID

👨‍💻 Development

Code Structure

Backend:

backend/src/app/
├── api/           # API route handlers
├── core/          # Configuration and security
├── models/        # SQLAlchemy ORM models
├── schemas/       # Pydantic validation schemas
├── repositories/  # Data access layer
└── services/      # Business logic

Frontend:

frontend/src/
├── components/    # Reusable UI components
├── pages/         # Page-level components
├── contexts/      # React context providers
├── services/      # API client services
└── lib/           # Utility functions

Available Dashboard Widgets

• Line Chart - Time series data visualization
• Bar Chart - Categorical comparisons with horizontal/vertical orientation
• Pie Chart - Distribution and proportions
• Stat Chart - Single KPI metric with optional trend indicators
• Table - Paginated data grid with sorting
• Timeline - Project milestones and events
• Map - Geographic data visualization with WMS/GeoJSON layers
• Free Text - Rich text content blocks

Adding New Features

1. Update Domain Model in backend/plantuml/buml_model.py
2. Regenerate Code with python generate.py
3. Create Migration if database schema changed
4. Update Frontend Services in frontend/src/services/
5. Add UI Components as needed
6. Test Thoroughly before deploying

📚 API Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

• GET /cities - List all cities
• GET /dashboards - List dashboards
• POST /dashboards/{id}/visualizations/bulk - Bulk create widgets
• GET /kpis - List key performance indicators
• POST /kpis/{id}/values/bulk - Bulk insert KPI data
• GET /mapdata/city/{city_code} - Get map layers for a city

Authentication

The API uses Keycloak for authentication:

1. Obtain access token from Keycloak
2. Include in request headers: Authorization: Bearer <token>
3. Token is validated via JWT verification

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Standards

• Python: Follow PEP 8, use type hints
• TypeScript: ESLint configuration, strict mode enabled
• Commits: Use conventional commits format
• Testing: Add tests for new features

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

📞 Contact & Support

• Project Website: https://climaplatform.eu
• Issue Tracker: GitHub Issues
• Documentation: Wiki

For support or questions, please open an issue on GitHub or contact the project maintainers.

---

Funded by the European Union 🇪🇺

This project has received funding from the European Union's Horizon 2020 research and innovation programme. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or CINEA. Neither the European Union nor the granting authority can be held responsible for them.