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.
- 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
βββββββββββββββ ββββββββββββββββ βββββββββββββββ
β External ββββββΆβ Data ββββββΆβ FastAPI β
β APIs β β Collectors β β Backend β
βββββββββββββββ ββββββββββββββββ ββββββββ¬βββββββ
β
ββββββββββββββββββββββββββββββΌβββββββββββββββββ
β β β
βββββββΌββββββ ββββββββΌβββββββ βββββββΌββββββ
β PostgreSQLβ β Redis β β WebSocket β
β Database β β Cache β β Server β
βββββββββββββ βββββββββββββββ βββββββ¬ββββββ
β
βββββββΌββββββ
β React β
β Frontend β
βββββββββββββ
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
- Python 3.11+
- Node.js 18+ and npm
- Docker & Docker Compose (recommended)
- PostgreSQL 15+ (if running locally)
- Redis 7+ (if running locally)
-
Clone the repository
git clone https://github.com/yourusername/citypulse.git cd citypulse -
Configure environment variables
cp .env.example .env # Edit .env with your configuration -
Start all services
docker-compose up -d
-
Access the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
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 8000cd frontend
# Install dependencies
npm install
# Start development server
npm run devKey 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=developmentGET /api/v1/events- List all eventsGET /api/v1/events/{id}- Get event detailsGET /api/v1/events/live- Real-time event stream (SSE)
GET /api/v1/analytics/overview- Dashboard overviewGET /api/v1/analytics/traffic- Traffic analyticsGET /api/v1/analytics/weather- Weather trendsGET /api/v1/analytics/predictions- Predictive analytics
GET /api/v1/sensors- List IoT sensorsGET /api/v1/sensors/{id}/data- Sensor data stream
GET /api/v1/alerts- List alertsPOST /api/v1/alerts- Create alert rulePUT /api/v1/alerts/{id}- Update alert
WS /ws/events- Real-time event streamWS /ws/sensors/{id}- Sensor data stream
cd backend
pytest tests/ -v --cov=appcd frontend
npm test- Set up infrastructure (EC2, RDS, ElastiCache)
- Configure security groups and VPC
- Deploy with Docker Compose or use ECS/EKS
- Set up CloudFront for frontend CDN
docker-compose.yml- Developmentdocker-compose.prod.yml- Production
- 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
- React 18 - UI framework
- Vite - Build tool
- Recharts - Data visualization
- Leaflet - Interactive maps
- TanStack Query - Data fetching
- Tailwind CSS - Styling
- PostgreSQL - Primary data store
- Redis - Cache and pub/sub
- Docker - Containerization
- Docker Compose - Multi-container orchestration
- GitHub Actions - CI/CD (optional)
Contributions are welcome! Please feel free to submit a Pull Request.
Your Name
- GitHub: @yourusername
- LinkedIn: Your LinkedIn
- Email: sadiqib0@outlook.com
- 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!