Skip to content

KEY_FILES_REFERENCE.md

Latest commit

 

History

History
328 lines (277 loc) · 8.53 KB

KEY_FILES_REFERENCE.md

File metadata and controls

328 lines (277 loc) · 8.53 KB

📁 Key Project Files Summary

Core Application Files

1. lib/main.dart

  • Purpose: App entry point and main navigation
  • Key Components:
    • AuthWrapper StatefulWidget for authentication flow
    • _checkAuth() method validates user session on startup
    • Route definitions for all screens
    • Provider setup for state management
  • Key Features:
    • Automatically routes to appropriate screen based on auth status
    • Handles role-based navigation

2. lib/services/tinydb_service.dart

  • Purpose: Local data storage abstraction
  • Backend: SharedPreferences (cross-platform)
  • Key Methods:
    • setString/getString - Basic key-value storage
    • setJson/getJson - JSON document storage
    • setStringList/getStringList - List storage
    • remove/clear - Data cleanup
  • Usage: Used throughout app for persistent local storage

3. lib/services/auth_service.dart

  • Purpose: User authentication (local-only)
  • Key Methods:
    • signUp() - Create new user (parent or child)
    • signIn() - Authenticate user locally
    • signOut() - Clear session
    • isSignedIn() - Check auth status
    • getCurrentUserId() - Get session user ID
    • getCurrentUserRole() - Get user role
    • linkChildToParent() - Create parent-child relationship
  • Data Storage: Uses TinyDB for user credentials

4. lib/Models/app_state.dart

  • Purpose: Global application state (Provider)
  • Key Properties:
    • userId - Current user ID
    • userRole - Current user role
    • username - Current user's username
    • ecoPoints - Total eco points
    • screenTimeMinutes - Green time tracked
    • waterSaved, co2Saved - Environmental impact
  • Key Methods:
    • setUserId() - Initialize user context
    • setEcoImpact() - Update environmental metrics
    • resetState() - Clear on logout
  • Used By: All screens via Provider.of<AppState>(context)

5. lib/Models/task.dart

  • Purpose: Task data model
  • Key Properties:
    • id, title, description - Task metadata
    • points - EcoPoints reward
    • kidID, parentID - Task assignment
    • status - Current task status
    • approvedByParent - Approval status
    • createdAt, completedAt - Timestamps
  • Key Methods:
    • Constructor for creating tasks
    • fromMap() factory - Create from TinyDB JSON
    • toJson() - Serialize for storage

Screen Files

6. lib/Screens/role_select.dart

  • Purpose: Initial role selection
  • Components:
    • RoleSelectScreen - Main screen
    • _RoleCard - Reusable role card widget
  • Features:
    • Beautiful gradient background
    • Two options: "I'm a Kid" and "I'm a Parent"
    • Routes to AuthScreen with role parameter
    • Responsive design

7. lib/Screens/auth_screen.dart

  • Purpose: User login and signup
  • Features:
    • Login/Signup toggle
    • Role-specific fields (child username)
    • Email & password validation
    • Form validation with helpers
    • Integrates with AuthService
    • Routes to appropriate dashboard on success

8. lib/Screens/child_dashboard.dart

  • Purpose: Child user's main interface
  • Features:
    • Display assigned tasks
    • Show EcoPoints and GreenTime counters
    • "Mark Done" button for task completion
    • Confetti celebration animation
    • Sign out functionality
    • Responsive layout with FutureBuilder
    • Material design cards and icons

9. lib/Screens/parent_dashboard.dart

  • Purpose: Parent user's main interface
  • Features:
    • Tab navigation (Pending/Approved tasks)
    • Task management (create, approve, reject, delete)
    • Environmental impact summary
    • Link children functionality
    • Add custom tasks dialog
    • Task approval workflow
    • Sign out option

10. lib/Screens/add_child_screen.dart

  • Purpose: Link children to parent account
  • Features:
    • Instructions card for parents
    • Child username input with validation
    • Link child button
    • Display linked children list
    • Remove child functionality
    • Loading indicator during linking

11. lib/Screens/redeem_screen.dart

  • Purpose: EcoPoints redemption
  • Features:
    • Display current EcoPoints
    • Info cards about redemption
    • WebView integration for external store
    • Role-based access (parents only)
    • Beautiful Material design

Configuration Files

12. pubspec.yaml

  • Purpose: Project dependencies and configuration
  • Key Dependencies:
    • Flutter & Dart SDK
    • UI: google_fonts, flutter_vector_icons, confetti, flutter_screenutil
    • State: provider
    • Storage: shared_preferences (TinyDB backend)
    • Other: image_picker, url_launcher, webview_flutter, intl, lottie
  • Removed: All Firebase packages (firebase_core, cloud_firestore, firebase_auth, etc.)

13. analysis_options.yaml

  • Purpose: Dart linting and analysis rules
  • Includes: Recommended lint rules for code quality

14. android/build.gradle.kts (Kotlin DSL)

  • Purpose: Android project build configuration
  • Content:
    • Build script dependencies
    • Repository configuration
    • Project-wide gradle settings

Test Files

15. test/test_tinydb.dart

  • Purpose: Unit tests for TinyDB functionality
  • Test Cases:
    • User signup validation
    • User signin validation
    • JSON storage and retrieval
  • Status: ✅ PASSING (00:26 +1: All tests passed!)

Documentation Files

16. FINAL_STATUS_REPORT.md ⭐

  • Complete project status summary
  • Architecture overview
  • Feature checklist
  • Testing results
  • Build instructions

17. IMPLEMENTATION_GUIDE.md ⭐

  • Quick start guide
  • Project structure explanation
  • Service documentation
  • User flows
  • Troubleshooting guide
  • Deployment instructions

Database Schema (TinyDB/SharedPreferences)

Storage Structure

Key: "users"
Value: {
  "user123": {
    "id": "user123",
    "email": "parent@example.com",
    "username": "parent_eco",
    "role": "parent",
    "ecoPoints": 500,
    "screenTimeMinutes": 2000,
    "waterSaved": 50.0,
    "co2Saved": 25.5,
    "createdAt": "2025-11-13T10:30:00Z"
  },
  "user456": {
    "id": "user456",
    "email": "child@example.com",
    "username": "eco_warrior_123",
    "role": "kid",
    "parentID": "user123",
    "ecoPoints": 250,
    "screenTimeMinutes": 1240,
    "createdAt": "2025-11-13T11:45:00Z"
  }
}

Key: "tasks"
Value: {
  "task_001": {
    "id": "task_001",
    "title": "Plant a Tree",
    "description": "Plant one tree in your area",
    "points": 50,
    "kidID": "user456",
    "parentID": "user123",
    "status": "pending",
    "approvedByParent": false,
    "createdAt": "2025-11-13T12:00:00Z"
  }
}

Key: "current_user"
Value: "user123"

Key: "current_role"
Value: "parent"

Key: "linked_children"
Value: "eco_warrior_123,another_child"

Build Output Locations

Windows Release

build/windows/x64/runner/Release/hi.exe

Windows Debug

build/windows/x64/runner/Debug/hi.exe

Android APK

build/app/outputs/flutter-apk/app-release.apk

iOS App

build/ios/iphoneos/Runner.app

Project Statistics

Metric Value
Dart Files 20+
Screen Files 6
Service Files 3
Model Files 3
Test Files 1+
Total Lines of Code 3,000+
Compilation Errors 0
Build Status ✅ PASSING
Test Status ✅ PASSING

Git Files (Documentation)

  • README.md - Project overview
  • QUICK_START.md - Quick reference
  • README_GREENTIME.md - GreenTime app info
  • COMMANDS_REFERENCE.md - CLI commands
  • MASTER_CHECKLIST.md - Project checklist

Important Notes

✅ What Works

  • Local authentication (no server needed)
  • Task creation and management
  • Parent-child relationships
  • EcoPoints tracking
  • Offline functionality
  • Cross-platform (ready for iOS/Android)
  • Responsive UI
  • Error handling
  • Data persistence

⚠️ Important Reminders

  1. No Cloud: App is 100% local - no Firebase or internet required
  2. Data Reset: Use TinyDB.clear() to reset all app data
  3. Passwords: Are stored as plain text in SharedPreferences (not production-ready for sensitive data)
  4. No Sync: Data doesn't sync between devices (each device has separate storage)
  5. Storage Limit: SharedPreferences has typical platform limits (usually 1-10MB)

🚀 Production Considerations

  • Implement proper password hashing (bcrypt/scrypt)
  • Add cloud sync (Firebase, Supabase, or custom backend)
  • Implement data validation
  • Add rate limiting
  • Implement proper logging
  • Add crash reporting
  • Consider database migration (SQLite → better for large datasets)

Reference Document Generated: November 13, 2025 Version: 1.0.0