<center>FIXIT - System Architecture Diagram
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ Web/Desktop (Flet) │ │ Mobile (Android/iOS - Flet) │ │
│ │ │ │ │ │
│ │ • Login Page │ │ • Login Page │ │
│ │ • Admin Dashboard │ │ • User Dashboard │ │
│ │ • User Dashboard │ │ • Report Submission │ │
│ │ • Report Management │ │ • Report Tracking │ │
│ │ • Category Reports │ │ │ │
│ │ • User Activity Monitor │ │ (Same UI/UX across platforms) │ │
│ └──────────────────────────┘ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER (Views) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Views Module (app/views/) │ │
│ │ │ │
│ │ ├── loginpage.py (Auth UI & Login Logic) │ │
│ │ ├── homepage.py (Welcome Page) │ │
│ │ │ │ │
│ │ ├── dashboard/ │ │
│ │ │ ├── admin/ │ │
│ │ │ │ ├── admin_dashboard.py │ │
│ │ │ │ ├── admin_all_reports.py │ │
│ │ │ │ ├── admin_all_categories.py │ │
│ │ │ │ ├── admin_category_reports.py │ │
│ │ │ │ ├── user_activity_monitoring.py │ │
│ │ │ │ ├── dashboard_ui.py │ │
│ │ │ │ ├── dashboard_controller.py │ │
│ │ │ │ └── dashboard_data_manager.py │ │
│ │ │ │ │ │
│ │ │ ├── user_dashboard.py │ │
│ │ │ ├── account_page.py │ │
│ │ │ ├── report_card.py │ │
│ │ │ ├── report_issue_page.py │ │
│ │ │ ├── report_statistics.py │ │
│ │ │ ├── navigation_drawer.py │ │
│ │ │ └── session_manager.py │ │
│ │ │ │ │
│ │ └── components/ │ │
│ │ └── session_timeout_ui.py │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ BUSINESS LOGIC LAYER (Services) │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────────────┐ │
│ │ Authentication Service │ │ Session Management Service │ │
│ │ (app/services/auth/) │ │ (app/services/session/) │ │
│ │ │ │ │ │
│ │ • admin_account.py │ │ • session_manager.py │ │
│ │ • Google OAuth │ │ - Create session │ │
│ │ │ │ - Validate session │ │
│ │ │ │ - Handle timeout │ │
│ │ │ │ - Refresh tokens │ │
│ └──────────────────────────┘ └───────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────────────┐ │
│ │ Database Service │ │ Audit & Activity Services │ │
│ │ (app/services/database/)│ │ (app/services/audit/ & activity/) │ │
│ │ │ │ │ │
│ │ • database.py │ │ • audit_logger.py │ │
│ │ • CRUD operations │ │ • activity_monitor.py │ │
│ │ • Query reports │ │ • user_activity_tracking.py │ │
│ │ • User management │ │ - Login attempts │ │
│ │ │ │ - Activity logging │ │
│ │ │ │ - Report actions │ │
│ └──────────────────────────┘ └───────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────────────┐ │
│ │ AI/ML Service │ │ Google OAuth Service │ │
│ │ (app/services/ai/) │ │ (app/services/google/) │ │
│ │ │ │ │ │
│ │ • ai_services.py │ │ • google_auth.py │ │
│ │ • ML model integration │ │ • OAuth 2.0 flow │ │
│ │ • Predictions │ │ • Token management │ │
│ │ • dataset.csv │ │ • User info retrieval │ │
│ └──────────────────────────┘ └───────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Security Services │ │
│ │ (app/services/csrf/, offline/) │ │
│ │ │ │
│ │ • CSRF Protection (csrf_token_manager.py) │ │
│ │ • Offline Mode Support (offline_service.py) │ │
│ │ • Data Sync (sync_manager.py) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Firestore Database │ │
│ │ (Cloud NoSQL Database) │ │
│ │ │ │
│ │ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ │
│ │ │ Collections │ │ Data Flow │ │ │
│ │ │ │ │ │ │ │
│ │ │ • users │ │ • Real-time sync enabled │ │ │
│ │ │ • reports │ │ • Automatic indexing │ │ │
│ │ │ • categories │ │ • Scalable storage │ │ │
│ │ │ • audit_logs │ │ • Cloud backups │ │ │
│ │ │ • activity_logs │ │ • Multi-region redundancy │ │ │
│ │ │ • sessions │ │ • Version control │ │ │
│ │ │ • failed_login... │ │ │ │ │
│ │ │ • account_lockouts │ │ │ │ │
│ │ │ • offline_queue │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ └──────────────────────┘ └──────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Local Storage (Development/Offline) │ │
│ │ │ │
│ │ • app_database.db (SQLite fallback) │ │
│ │ • storage/data/ (Local JSON files) │ │
│ │ • storage/temp/ (Temporary files) │ │
│ │ • Session cache │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL SERVICES / APIs │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────────────┐ │
│ │ Google Services │ │ Cloud Services │ │
│ │ │ │ │ │
│ │ • Google OAuth 2.0 │ │ • Google Cloud Platform │ │
│ │ • Gmail API │ │ - Firestore Database │ │
│ │ • User authentication │ │ - Cloud Storage │ │
│ │ • Profile info │ │ - Cloud Functions (optional) │ │
│ │ │ │ │ │
│ └──────────────────────────┘ └───────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Data Flow Diagrams
Authentication Flow
┌─────────────┐
│ User │
└──────┬──────┘
│ 1. Enter credentials/Click CSPC Email
↓
┌─────────────────────────────┐
│ Login Page │
│ - Validate input │
│ - Check account lockout │ ← Credential Stuffing Protection
│ - Call auth service │
└──────────┬──────────────────┘
│
├─ 2a. Admin Path ──→ validate_admin_credentials()
│ ↓
│ admin_account.py checks:
│ • Email format
│ • Password hash
│
└─ 2b. OAuth Path ──→ google_oauth_login()
↓
google_auth.py:
• Redirects to Google
• Gets auth code
• Exchanges for token
• Gets user info
↓
┌─────────────────────────┐
│ Create Session │
│ • session_manager │
│ • Set timeout │
│ • Store user data │
└──────────┬──────────────┘
│
↓
┌─────────────────────────┐
│ Log Activities │
│ • audit_logger.py │
│ • activity_monitor.py │
└──────────┬──────────────┘
│
↓
┌─────────────────────────┐
│ Load Dashboard │
│ • User/Admin │
│ • Load reports │
│ • Setup session │
└─────────────────────────┘
Report Submission Flow
┌──────────────────────────┐
│ User Dashboard Page │
│ - Submit Report Form │
└───────────┬──────────────┘
│ 1. Fill form (description, location, category)
↓
┌──────────────────────────┐
│ Validation Layer │
│ - Input validation │
│ - Sanitization │
│ - CSRF check │
└───────────┬──────────────┘
│ 2. Valid data
↓
┌──────────────────────────┐
│ Database Service │
│ db.add_report() │
│ - Generate unique ID │
│ - Add timestamp │
│ - Store in Firestore │
└───────────┬──────────────┘
│ 3. Document created
↓
┌──────────────────────────┐
│ Audit & Activity Log │
│ - Log submission │
│ - Record timestamp │
│ - Track user activity │
└───────────┬──────────────┘
│ 4. Confirmation
↓
┌──────────────────────────┐
│ Show Success Message │
│ - Report ID │
│ - Track link │
└──────────────────────────┘
Admin Report Management Flow
┌──────────────────────────┐
│ Admin Dashboard │
│ - View all reports │
│ - Filter by category │
│ - Search functionality │
└───────────┬──────────────┘
│
┌──────┴──────┬─────────────┐
│ │ │
↓ ↓ ↓
┌─────────┐ ┌──────────┐ ┌──────────┐
│ View │ │ Update │ │ View by │
│ Details │ │ Status │ │ Category │
└────┬────┘ └────┬─────┘ └────┬─────┘
│ │ │
└────────────┴─────────────┘
│
↓
┌──────────────────────────┐
│ Database Service │
│ - Query reports │
│ - Update status │
│ - Fetch by category │
└───────────┬──────────────┘
│
↓
┌──────────────────────────┐
│ Audit Log │
│ - Log all changes │
│ - Track admin actions │
│ - Timestamp changes │
└──────────────────────────┘
Security Architecture
┌─────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────┤
│ │
│ Layer 1: Input Validation & Sanitization │
│ ├── HTML/Script injection prevention │
│ ├── SQL injection prevention (NoSQL) │
│ ├── Email format validation │
│ └── Rate limiting on API calls │
│ │
│ Layer 2: Authentication & Authorization │
│ ├── Admin credentials (email + password hashing) │
│ ├── OAuth 2.0 (Google) │
│ ├── Session management │
│ ├── Role-based access control (RBAC) │
│ └── Session timeout │
│ │
│ Layer 3: Credential Stuffing Protection │
│ ├── Failed attempt tracking │
│ ├── Account lockout (3 attempts = 15 min) │
│ ├── Hard lockout (5+ attempts = 30 min) │
│ ├── Graduated response │
│ └── Time-window based throttling (15 min) │
│ │
│ Layer 4: CSRF Protection │
│ ├── CSRF token generation │
│ ├── Token validation on form submission │
│ ├── Session-based token storage │
│ └── Token rotation on login │
│ │
│ Layer 5: Data Protection │
│ ├── HTTPS/TLS encryption │
│ ├── Password hashing (SHA-256) │
│ ├── Sensitive data encryption │
│ └── Secure token storage │
│ │
│ Layer 6: Audit & Monitoring │
│ ├── Comprehensive audit logs │
│ ├── Activity tracking │
│ ├── Security event logging │
│ ├── Admin user monitoring │
│ └── Suspicious activity detection │
│ │
│ Layer 7: Offline Security │
│ ├── Local encryption │
│ ├── Secure sync on reconnect │
│ └── Offline mode indicators │
│ │
└─────────────────────────────────────────────────────────┘
Technology Stack
┌────────────────────────────────────────────────────────────┐
│ TECHNOLOGY STACK │
├────────────────────────────────────────────────────────────┤
│ │
│ Frontend: │
│ ├── Flet 0.28.3 (Python UI Framework) │
│ ├── Cross-platform (Web, Desktop, Mobile) │
│ ├── Material Design UI │
│ └── Real-time updates │
│ │
│ Backend: │
│ ├── Python 3.x │
│ ├── FastAPI (optional for API) │
│ └── Service-oriented architecture │
│ │
│ Database: │
│ ├── Firestore (Primary - Cloud NoSQL) │
│ ├── SQLite (Fallback for dev) │
│ └── JSON files (Local storage) │
│ │
│ Authentication: │
│ ├── Google OAuth 2.0 │
│ ├── Custom admin accounts │
│ ├── JWT tokens (for sessions) │
│ └── Password hashing │
│ │
│ Cloud Services: │
│ ├── Google Cloud Platform │
│ ├── Firestore Database │
│ ├── Cloud Storage (optional) │
│ └── Cloud Functions (optional) │
│ │
│ Dependencies: │
│ ├── firebase-admin 6.5.0 │
│ ├── google-cloud-firestore 2.17.0 │
│ ├── google-auth 2.41.1 │
│ ├── requests 2.32.5 │
│ └── python-dotenv 1.2.1 │
│ │
└────────────────────────────────────────────────────────────┘
Component Interaction Matrix
┌─────────────────────────────────────────────────────────────────────────┐
│ COMPONENT COMMUNICATION MATRIX │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Views/UI ←→ Services ←→ Database ←→ External APIs │
│ ───────── ──────── ──────── ──────────── │
│ │
│ loginpage ←→ auth_svc ←→ Firestore ←→ Google OAuth │
│ admin_dashboard ←→ database_svc ←→ Firestore │
│ user_dashboard ←→ session_mgr ←→ Firestore ←→ (offline sync) │
│ report_card ←→ audit_log ←→ Firestore │
│ account_page ←→ activity_mon ←→ Firestore ←→ (analytics) │
│ navigation_drawer ←→ csrf_protect ←→ Sessions │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Deployment Architecture
┌──────────────────────────────────────────────────────────────┐
│ DEPLOYMENT ARCHITECTURE │
├──────────────────────────────────────────────────────────────┤
│ │
│ Development Production │
│ ─────────── ────────── │
│ │
│ Local Machine ──→ Google Cloud │
│ ├── Python 3.x ├── Firestore Database │
│ ├── Flet CLI ├── Cloud Storage │
│ ├── SQLite DB ├── Cloud Functions │
│ └── Firebase Emulator ├── Cloud Run (optional) │
│ ├── Identity & Access Mgmt │
│ Testing └── Cloud Monitoring │
│ ├── Unit tests |
│ ├── Integration tests CDN / Security │
│ └── Manual testing ├── Cloud CDN │
│ ├── Cloud Armor │
│ Version Control ├── Secret Manager │
│ ├── Git (GitHub) └── SSL/TLS Certificates │
│ └── Dev/Staging/Main │
│ branches Backups & Redundancy │
│ ├── Automated backups │
│ ├── Multi-region replication │
│ └── Point-in-time recovery │
│ │
└──────────────────────────────────────────────────────────────┘
Session & State Management
┌─────────────────────────────────────────────────────────┐
│ SESSION & STATE MANAGEMENT │
├─────────────────────────────────────────────────────────┤
│ │
│ Session Lifecycle: │
│ 1. Login │
│ └─→ Create session in session_manager │
│ └─→ Generate session ID & token │
│ └─→ Store in Firestore │
│ │
│ 2. Active Session │
│ └─→ session_manager validates token on each action │
│ └─→ Update last_activity timestamp │
│ └─→ Check timeout (15-30 min default) │
│ └─→ Show warning UI before expiry │
│ │
│ 3. Timeout │
│ └─→ session_manager detects inactivity │
│ └─→ Trigger timeout callbacks │
│ └─→ Redirect to login │
│ └─→ Log session end │
│ │
│ 4. Logout │
│ └─→ User clicks logout │
│ └─→ Destroy session in Firestore │
│ └─→ Clear local tokens │
│ └─→ Log logout event │
│ │
│ Offline Mode: │
│ - Queue operations locally │
│ - Sync on reconnect │
│ - Maintain session state │
│ │
└─────────────────────────────────────────────────────────┘
File Structure
CCCS_106_FINAL_PROJECT/
│
├── main.py # Application entry point
├── requirements.txt # Python dependencies
├── README.md # Project documentation
│
├── app/
│ ├── __init__.py
│ │
│ ├── views/ # Presentation Layer
│ │ ├── loginpage.py # Authentication UI
│ │ ├── homepage.py # Welcome page
│ │ │
│ │ └── dashboard/
│ │ ├── admin/ # Admin-specific views
│ │ │ ├── admin_dashboard.py
│ │ │ ├── admin_all_reports.py
│ │ │ ├── dashboard_ui.py
│ │ │ └── ...
│ │ │
│ │ ├── user_dashboard.py
│ │ ├── account_page.py
│ │ ├── report_card.py
│ │ ├── navigation_drawer.py
│ │ └── ...
│ │
│ └── services/ # Business Logic Layer
│ ├── auth/ # Authentication services
│ │ ├── admin_account.py
│ │ └── ...
│ │
│ ├── database/ # Data access layer
│ │ └── database.py # CRUD operations
│ │
│ ├── session/ # Session management
│ │ └── session_manager.py
│ │
│ ├── audit/ # Audit logging
│ │ └── audit_logger.py
│ │
│ ├── activity/ # Activity monitoring
│ │ ├── activity_monitor.py
│ │ └── ...
│ │
│ ├── google/ # OAuth integration
│ │ └── google_auth.py
│ │
│ ├── ai/ # AI/ML services
│ │ └── ai_services.py
│ │
│ ├── csrf/ # CSRF protection
│ │ └── csrf_token_manager.py
│ │
│ ├── offline/ # Offline support
│ │ ├── offline_service.py
│ │ └── sync_manager.py
│ │
│ └── firebase/ # Cloud integration
│ └── firebase_config.py
│
├── storage/ # Local storage
│ ├── data/ # Persistent data
│ └── temp/ # Temporary files
│
└── assets/ # Static assets
└── fonts/ # Custom fonts