Skip to content

Repository files navigation

πŸŒ† CityPulse - Real-Time Event & Analytics Platform

Python FastAPI React PostgreSQL Redis

A production-grade real-time data platform that collects, streams, analyzes, and visualizes city events, traffic patterns, weather data, and IoT sensor readings. Built with modern technologies and scalable architecture.

🎯 Features

  • Real-Time Data Streaming: WebSocket-based live data feeds with fallback to SSE
  • Multi-Source Data Collection: Traffic, weather, social events, and simulated IoT sensors
  • Advanced Analytics: Time-series analysis, anomaly detection, and predictive insights
  • Interactive Dashboards: Beautiful, responsive UI with live charts and maps
  • Alert System: Configurable threshold-based alerting with notification channels
  • RESTful API: Comprehensive API with OpenAPI documentation
  • Scalable Architecture: Microservices-ready with Docker containerization
  • Data Persistence: PostgreSQL for structured data, Redis for caching and real-time state

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   External  │────▢│  Data        │────▢│  FastAPI    β”‚
β”‚   APIs      β”‚     β”‚  Collectors  β”‚     β”‚  Backend    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜
                                                 β”‚
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚                            β”‚                β”‚
              β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”              β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”
              β”‚ PostgreSQLβ”‚              β”‚    Redis    β”‚   β”‚ WebSocket β”‚
              β”‚  Database β”‚              β”‚    Cache    β”‚   β”‚  Server   β”‚
              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜
                                                                  β”‚
                                                            β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”
                                                            β”‚   React   β”‚
                                                            β”‚  Frontend β”‚
                                                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ“ Project Structure

citypulse/
β”œβ”€β”€ backend/                    # Python FastAPI backend
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ api/               # API endpoints
β”‚   β”‚   β”‚   β”œβ”€β”€ v1/
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ endpoints/ # Route handlers
β”‚   β”‚   β”‚   β”‚   └── deps.py    # Dependencies
β”‚   β”‚   β”‚   └── websocket.py   # WebSocket handlers
β”‚   β”‚   β”œβ”€β”€ core/              # Core configurations
β”‚   β”‚   β”‚   β”œβ”€β”€ config.py
β”‚   β”‚   β”‚   β”œβ”€β”€ security.py
β”‚   β”‚   β”‚   └── events.py
β”‚   β”‚   β”œβ”€β”€ db/                # Database layer
β”‚   β”‚   β”‚   β”œβ”€β”€ base.py
β”‚   β”‚   β”‚   β”œβ”€β”€ session.py
β”‚   β”‚   β”‚   └── init_db.py
β”‚   β”‚   β”œβ”€β”€ models/            # SQLAlchemy models
β”‚   β”‚   β”œβ”€β”€ schemas/           # Pydantic schemas
β”‚   β”‚   β”œβ”€β”€ services/          # Business logic
β”‚   β”‚   β”‚   β”œβ”€β”€ collectors/    # Data collectors
β”‚   β”‚   β”‚   β”œβ”€β”€ analytics/     # Analytics engine
β”‚   β”‚   β”‚   └── alerts/        # Alert system
β”‚   β”‚   β”œβ”€β”€ utils/             # Utilities
β”‚   β”‚   └── main.py            # Application entry point
β”‚   β”œβ”€β”€ tests/                 # Backend tests
β”‚   β”œβ”€β”€ alembic/               # Database migrations
β”‚   β”œβ”€β”€ requirements.txt
β”‚   └── Dockerfile
β”œβ”€β”€ frontend/                   # React frontend
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ components/        # React components
β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard/
β”‚   β”‚   β”‚   β”œβ”€β”€ charts/
β”‚   β”‚   β”‚   β”œβ”€β”€ maps/
β”‚   β”‚   β”‚   └── common/
β”‚   β”‚   β”œβ”€β”€ hooks/             # Custom React hooks
β”‚   β”‚   β”œβ”€β”€ services/          # API client services
β”‚   β”‚   β”œβ”€β”€ store/             # State management
β”‚   β”‚   β”œβ”€β”€ utils/             # Utilities
β”‚   β”‚   β”œβ”€β”€ styles/            # Global styles
β”‚   β”‚   β”œβ”€β”€ App.jsx
β”‚   β”‚   └── main.jsx
β”‚   β”œβ”€β”€ public/
β”‚   β”œβ”€β”€ package.json
β”‚   └── Dockerfile
β”œβ”€β”€ docker-compose.yml          # Docker orchestration
β”œβ”€β”€ .env.example               # Environment variables template
β”œβ”€β”€ .gitignore
└── README.md

πŸš€ Quick Start

Prerequisites

  • Python 3.11+
  • Node.js 18+ and npm
  • Docker & Docker Compose (recommended)
  • PostgreSQL 15+ (if running locally)
  • Redis 7+ (if running locally)

Option 1: Docker (Recommended)

  1. Clone the repository

    git clone https://github.com/yourusername/citypulse.git
    cd citypulse
  2. Configure environment variables

    cp .env.example .env
    # Edit .env with your configuration
  3. Start all services

    docker-compose up -d
  4. Access the application

Option 2: Local Development

Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up database
alembic upgrade head

# Start the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

πŸ”§ Configuration

Key environment variables (see .env.example):

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/citypulse
REDIS_URL=redis://localhost:6379/0

# API Keys (Optional - for real data)
OPENWEATHER_API_KEY=your_key_here
TRAFFIC_API_KEY=your_key_here

# Application
SECRET_KEY=your-secret-key-here
ENVIRONMENT=development

πŸ“Š API Endpoints

Events

  • GET /api/v1/events - List all events
  • GET /api/v1/events/{id} - Get event details
  • GET /api/v1/events/live - Real-time event stream (SSE)

Analytics

  • GET /api/v1/analytics/overview - Dashboard overview
  • GET /api/v1/analytics/traffic - Traffic analytics
  • GET /api/v1/analytics/weather - Weather trends
  • GET /api/v1/analytics/predictions - Predictive analytics

Sensors

  • GET /api/v1/sensors - List IoT sensors
  • GET /api/v1/sensors/{id}/data - Sensor data stream

Alerts

  • GET /api/v1/alerts - List alerts
  • POST /api/v1/alerts - Create alert rule
  • PUT /api/v1/alerts/{id} - Update alert

WebSocket

  • WS /ws/events - Real-time event stream
  • WS /ws/sensors/{id} - Sensor data stream

πŸ§ͺ Testing

Backend Tests

cd backend
pytest tests/ -v --cov=app

Frontend Tests

cd frontend
npm test

πŸ“¦ Deployment

AWS Deployment

  1. Set up infrastructure (EC2, RDS, ElastiCache)
  2. Configure security groups and VPC
  3. Deploy with Docker Compose or use ECS/EKS
  4. Set up CloudFront for frontend CDN

Environment-specific configs

  • docker-compose.yml - Development
  • docker-compose.prod.yml - Production

🎨 Tech Stack

Backend

  • FastAPI - Modern Python web framework
  • SQLAlchemy - ORM for database operations
  • Alembic - Database migrations
  • Pydantic - Data validation
  • Redis - Caching and real-time state
  • WebSockets - Real-time communication

Frontend

  • React 18 - UI framework
  • Vite - Build tool
  • Recharts - Data visualization
  • Leaflet - Interactive maps
  • TanStack Query - Data fetching
  • Tailwind CSS - Styling

Database

  • PostgreSQL - Primary data store
  • Redis - Cache and pub/sub

DevOps

  • Docker - Containerization
  • Docker Compose - Multi-container orchestration
  • GitHub Actions - CI/CD (optional)

🀝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

πŸ‘¨β€πŸ’» Author

Your Name

πŸ™ Acknowledgments

  • Weather data from OpenWeatherMap
  • Traffic data simulation inspired by real-world patterns
  • Icon design by Heroicons

⭐ If you found this project helpful, please give it a star!

About

"Real-Time Event & Analytics Platform for Smart Cities"

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages