ARCHITECTURE.md

System Architecture

Overview

The Water Quality Monitoring System follows a modern full-stack architecture using Next.js for both frontend and backend, MongoDB for data persistence, and MQTT for real-time sensor data ingestion.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        PRESENTATION LAYER                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              Next.js Frontend (React 18)                  │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  • SensorMap Component (Leaflet.js)                       │  │
│  │  • Dashboard with Charts (Recharts)                       │  │
│  │  • Real-time Updates (Polling)                            │  │
│  │  • Responsive UI (Tailwind CSS)                           │  │
│  └──────────────────────────────────────────────────────────┘  │
│                               ▲                                  │
│                               │ HTTP/REST                        │
│                               ▼                                  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                       APPLICATION LAYER                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │           Next.js API Routes (Node.js)                    │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  GET  /api/sensors        - List all sensors              │  │
│  │  POST /api/sensors        - Create new sensor             │  │
│  │  GET  /api/readings       - Get historical readings       │  │
│  └──────────────────────────────────────────────────────────┘  │
│                               ▲                                  │
│                               │                                  │
│                               ▼                                  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                         DATA LAYER                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                     MongoDB Database                      │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  • sensors collection                                     │  │
│  │    - sensorId (indexed)                                   │  │
│  │    - location (2dsphere index)                            │  │
│  │                                                            │  │
│  │  • readings collection                                    │  │
│  │    - sensorId + timestamp (compound index)                │  │
│  │    - timestamp (indexed for queries)                      │  │
│  │                                                            │  │
│  │  Retention: 5 years                                       │  │
│  └──────────────────────────────────────────────────────────┘  │
│                               ▲                                  │
└───────────────────────────────┼──────────────────────────────────┘
                                │
┌───────────────────────────────┼──────────────────────────────────┐
│                        INGESTION LAYER                           │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │            MQTT Ingestion Service (Node.js)               │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  • Subscribe to MQTT topics                               │  │
│  │  • Validate incoming readings                             │  │
│  │  • Store in MongoDB                                       │  │
│  │  • Error handling & logging                               │  │
│  └──────────────────────────────────────────────────────────┘  │
│                               ▲                                  │
│                               │ MQTT Protocol                    │
│                               │                                  │
└───────────────────────────────┼──────────────────────────────────┘
                                │
┌───────────────────────────────┼──────────────────────────────────┐
│                         SENSOR LAYER                             │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  Sensor 1   │  │  Sensor 2   │  │  Sensor N   │             │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤             │
│  │ • pH        │  │ • pH        │  │ • pH        │             │
│  │ • Turbidity │  │ • Turbidity │  │ • Turbidity │             │
│  │ • Temp      │  │ • Temp      │  │ • Temp      │             │
│  │ • Hardness  │  │ • Hardness  │  │ • Hardness  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                   │
│  Fixed geographic locations                                      │
│  Random transmission intervals                                   │
└──────────────────────────────────────────────────────────────────┘

Component Details

1. Frontend (React/Next.js)

Key Components:

• SensorMap: Main container component managing state
• MapView: Leaflet.js integration for interactive mapping
• SensorDashboard: Charts and statistics display

Features:

• Interactive global map with zoomable interface
• Marker clustering for performance
• Real-time data updates (30-second polling)
• Responsive design for mobile/desktop
• Time-series visualization with Recharts

State Management:

• React hooks (useState, useEffect)
• Local component state
• No Redux/Context needed (simple state)

2. API Layer (Next.js API Routes)

Endpoints:

GET /api/sensors
Response: SensorWithLatestReading[]
- Returns all sensors with their most recent reading
- Efficient aggregation using MongoDB pipelines

GET /api/readings?sensorId=XXX&timeRange=1d
Response: Reading[]
- Time-filtered readings for a specific sensor
- Supports: 1h, 1d, 1w, 1m, custom ranges
- Optimized queries with indexed timestamps

POST /api/sensors
Request: { sensorId, latitude, longitude, locationName? }
Response: Sensor
- Create new sensor record
- Auto-generates installedAt timestamp

Features:

• RESTful design
• Input validation
• Error handling with proper status codes
• Connection pooling for MongoDB

3. MQTT Ingestion Service

Responsibilities:

• Subscribe to MQTT broker topics
• Parse and validate incoming JSON messages
• Store validated readings in MongoDB
• Log invalid/malformed messages
• Handle connection failures gracefully

Data Validation:

{
  sensorId: required,
  timestamp: required (ISO date),
  pH: 0-14,
  turbidity: >= 0,
  temperature: -50 to 100°C,
  hardness: >= 0
}

Error Handling:

• Retry logic for MongoDB failures
• Graceful reconnection to MQTT broker
• Detailed error logging

4. Database (MongoDB)

Collections:

sensors:

{
  _id: ObjectId,
  sensorId: "SENSOR_XXX_001",
  latitude: 40.7128,
  longitude: -74.0060,
  locationName: "New York City",
  installedAt: ISODate("2020-01-15")
}

Indexes:

• { sensorId: 1 } - Unique index for lookups
• { location: "2dsphere" } - Geospatial queries

readings:

{
  _id: ObjectId,
  sensorId: "SENSOR_XXX_001",
  timestamp: ISODate("2024-02-16T10:30:00Z"),
  pH: 7.2,
  turbidity: 3.5,
  temperature: 22.1,
  hardness: 150.0
}

Indexes:

• { sensorId: 1, timestamp: -1 } - Compound index for sensor queries
• { timestamp: -1 } - Time-based filtering

Retention Policy:

• TTL index for 5-year retention (future implementation)
• Archive strategy for historical data

Data Flow

1. Sensor Reading Flow

Sensor Device
    │
    │ MQTT Publish
    ▼
MQTT Broker (HiveMQ)
    │
    │ Subscribe
    ▼
Ingestion Service
    │
    │ Validate
    ▼
MongoDB (readings)
    │
    │ Query (via API)
    ▼
Next.js Frontend
    │
    │ Render
    ▼
User Browser

2. User Query Flow

User clicks sensor
    │
    ▼
Frontend fetches data
    │
    ▼
API Route handler
    │
    ▼
MongoDB query
    │
    ▼
Data aggregation
    │
    ▼
JSON response
    │
    ▼
Chart rendering

Scalability Considerations

Current Scale

• 10-100 sensors: Easily handled
• 1 reading/sensor/hour: ~240 readings/day per sensor
• 5 years retention: ~440K readings per sensor

Scaling Strategies

Horizontal Scaling:

• Multiple MQTT ingestion workers
• Load balancer for Next.js instances
• MongoDB replica sets

Vertical Scaling:

• Increased server resources
• MongoDB sharding by sensorId
• Redis caching layer

Optimization:

• Data aggregation pre-computation
• CDN for static assets
• Query result caching

Security Considerations

Current Status (Development):

• No authentication (as per PRD requirements)
• Public MQTT broker
• Open API endpoints

Production Recommendations:

• JWT authentication for APIs
• MQTT broker with TLS/SSL
• Role-based access control
• API rate limiting
• Input sanitization
• Environment variable protection

Monitoring & Observability

Recommended Tools:

• Application logs (Winston/Pino)
• MongoDB Atlas monitoring
• MQTT broker metrics
• Error tracking (Sentry)
• Performance monitoring (New Relic)

Key Metrics:

• Sensor uptime
• Reading ingestion rate
• API response times
• Database query performance
• Error rates

Technology Choices Rationale

Technology	Reason
Next.js	Full-stack framework, API routes, SSR/SSG
MongoDB	Flexible schema, time-series data, geospatial queries
MQTT	Lightweight, efficient for IoT, publish-subscribe
Leaflet	Open-source, customizable mapping
Recharts	React-friendly, responsive charts
TypeScript	Type safety, better developer experience

Future Enhancements

1. Real-time Updates: WebSocket integration
2. Advanced Analytics: ML-based anomaly detection
3. Alerting System: Email/SMS notifications
4. Data Export: CSV/PDF generation
5. Mobile App: React Native implementation
6. Admin Panel: Sensor management interface
7. Authentication: User accounts and permissions
8. Caching Layer: Redis for frequently accessed data

---

This architecture supports the current requirements while providing a foundation for future enhancements and scale.