sac4cps-backend/ARCHITECTURE.md

Backend Architecture Restructuring

Overview

The backend has been restructured from a monolithic approach to a clean 3-layer architecture with proper separation of concerns.

Architecture Layers

1. Infrastructure Layer (layers/infrastructure/)

Responsibility: Data access, external services, and low-level operations

• database_connection.py - MongoDB connection management and indexing
• redis_connection.py - Redis connection and basic operations
• repositories.py - Data access layer with repository pattern

Key Principles:

• No business logic
• Only handles data persistence and retrieval
• Provides abstractions for external services

2. Business Layer (layers/business/)

Responsibility: Business logic, data processing, and core application rules

• sensor_service.py - Sensor data processing and validation
• room_service.py - Room metrics calculation and aggregation
• analytics_service.py - Analytics calculations and reporting
• cleanup_service.py - Data retention and maintenance

Key Principles:

• Contains all business rules and validation
• Independent of presentation concerns
• Uses infrastructure layer for data access

3. Presentation Layer (layers/presentation/)

Responsibility: HTTP endpoints, WebSocket handling, and user interface

• api_routes.py - REST API endpoints and request/response handling
• websocket_handler.py - WebSocket connection management
• redis_subscriber.py - Real-time data broadcasting

Key Principles:

• Handles HTTP requests and responses
• Manages real-time communications
• Delegates business logic to business layer

File Comparison

Before (Monolithic)

main.py (203 lines)           # Mixed concerns
api.py (506 lines)           # API + some business logic  
database.py (220 lines)      # DB + Redis + cleanup
persistence.py (448 lines)   # Business + data access
models.py (236 lines)        # Data models

After (Layered)

Infrastructure Layer:
├── database_connection.py (114 lines)    # Pure DB connection
├── redis_connection.py (89 lines)       # Pure Redis connection  
└── repositories.py (376 lines)          # Clean data access

Business Layer:
├── sensor_service.py (380 lines)        # Sensor business logic
├── room_service.py (242 lines)         # Room business logic
├── analytics_service.py (333 lines)     # Analytics business logic
└── cleanup_service.py (278 lines)       # Cleanup business logic

Presentation Layer:
├── api_routes.py (430 lines)           # Pure API endpoints
├── websocket_handler.py (103 lines)    # WebSocket management
└── redis_subscriber.py (148 lines)     # Real-time broadcasting

Core:
├── main_layered.py (272 lines)         # Clean application entry
└── models.py (236 lines)               # Unchanged data models

Key Improvements

1. Separation of Concerns

• Each layer has a single, well-defined responsibility
• Infrastructure concerns isolated from business logic
• Business logic separated from presentation

2. Testability

• Each layer can be tested independently
• Business logic testable without database dependencies
• Infrastructure layer testable without business complexity

3. Maintainability

• Changes in one layer don't affect others
• Clear boundaries make code easier to understand
• Reduced coupling between components

4. Scalability

• Layers can be scaled independently
• Easy to replace implementations within layers
• Clear extension points for new features

5. Dependency Management

• Clear dependency flow: Presentation → Business → Infrastructure
• No circular dependencies
• Infrastructure layer has no knowledge of business rules

Usage

Running the Layered Application

# Use the new layered main file
conda activate dashboard
uvicorn main_layered:app --reload

Testing the Structure

# Validate the architecture
python test_structure.py

Benefits Achieved

✅ Clear separation of concerns
✅ Infrastructure isolated from business logic
✅ Business logic separated from presentation
✅ Easy to test individual layers
✅ Maintainable and scalable structure
✅ No layering violations detected
✅ 2,290+ lines properly organized across 10+ files

Migration Path

The original files are preserved, so you can:

1. Test the new layered architecture with main_layered.py
2. Gradually migrate consumers to use the new structure
3. Remove old files once confident in the new architecture

Both architectures can coexist during the transition period.