NOVA - Enterprise Flutter Migration & Code Analysis Platform

---

Executive Summary

NOVA is an enterprise-grade static code analysis, automated refactoring, and technical debt measurement platform designed specifically for Flutter codebases. Built with a responsive, glassmorphic Web interface, NOVA enables engineering teams to upload legacy Flutter project archives (.zip), execute automated Abstract Syntax Tree (AST) parsing, identify deprecated API patterns (such as legacy buttons, navigation constructs, and color opacity usages), compute technical debt metrics, and generate fully modernized code packages ready for deployment.

The platform combines a modern reactive Flutter Web client powered by Riverpod, GoRouter, and Freezed with an asynchronous FastAPI Python backend engine to deliver seamless, real-time code transformations.

---

System Architecture & Data Flow

NOVA operates as a decoupled client-server platform. The Flutter Web client manages state, user authentication, and reactive Firestore subscriptions, while the FastAPI Python service performs CPU-intensive AST parsing, code transformation, and archive packaging.

High-Level System Architecture

graph TD
    Client["NOVA Flutter Web Client (Port 3000)"]
    Router["GoRouter Top-Level Navigation"]
    Providers["Riverpod State Management & Repositories"]
    ApiClient["Dio ApiClient HTTP Layer"]
    Firebase["Firebase Auth / Cloud Firestore / Cloud Storage"]
    Backend["FastAPI Python Engine (Port 8000)"]
    Scraper["Flutter Release Scraper (docs.flutter.dev)"]

    Client --> Router
    Client --> Providers
    Providers --> ApiClient
    Providers --> Firebase
    ApiClient -->|REST API Requests| Backend
    Backend -->|Live Scrape| Scraper
    Backend -->|Persist Analysis Doc| Firebase

Loading

End-to-End Migration Data Flow

sequenceDiagram
    autonumber
    participant Developer as User / Developer
    participant Web as Flutter Web App
    participant Repo as Riverpod Repository
    participant Dio as ApiClient (Dio)
    participant API as FastAPI Backend
    participant DB as Cloud Firestore

    Developer->>Web: Uploads legacy Flutter project (.zip)
    Web->>Repo: Triggers project creation
    Repo->>Dio: Dispatches multipart POST /analyze
    Dio->>API: Transmits zip archive & parameters
    API->>API: Extracts zip, parses AST, runs refactoring
    API->>DB: Saves analysis document with status="completed"
    API-->>Dio: Returns 200 OK with analysis payload
    Dio-->>Web: Updates reactive UI with analysis summary
    Developer->>Web: Clicks "Download Migrated Project"
    Web->>Dio: Dispatches GET /download-fixed/{projectId}
    Dio->>API: Fetches refactored .zip archive
    API-->>Web: Streams modernized project package

Loading

---

Key Capabilities

• Abstract Syntax Tree (AST) Code Refactoring: Analyzes Dart source files to detect deprecated API usages and automatically rewrite source code to current Flutter 3.x specifications.
• Reactive State Architecture: Built on Riverpod providers and auto-disposing state streams for real-time reactivity without state leaks.
• Declarative Web Routing: Integrates GoRouter for deep-linking, browser history navigation, and seamless URL state synchronization.
• Typed Network Abstraction: Employs a custom Dio ApiClient with configurable request/response timeouts, logging interceptors, and error handlers.
• Immutable Freezed Data Models: Models (FlutterProject, AnalysisResult, DeprecatedUsage) generated with Freezed and JSON Serializable for type-safe immutability.
• Live Flutter Breaking Changes Radar: Asynchronously scrapes official Flutter release notes to surface live breaking change notices categorized by framework module.
• Cursor-Based Firestore Pagination: Supports high-performance document pagination (startAfterDocument) for workspace project lists and migration histories.
• Side-by-Side Code Diff Viewer: Visualizes line-by-line comparisons between original legacy source files and modernized refactored output.
• Glassmorphic Light & Dark Theme Design: Crafted with custom glassmorphic tokens (NovaColors, GlassCard, GlassButton, GlassTextField) featuring frosted glass aesthetics and high-contrast typography.

---

Technical Stack

Layer	Technology	Version	Function & Responsibility
Frontend Framework	Flutter Web	>=3.0.0	Client application rendered via CanvasKit / HTML
State Management	Flutter Riverpod	^2.5.1	Reactive provider graph and state management
Routing Engine	GoRouter	^14.0.0	Declarative URL routing and web deep-linking
HTTP Client	Dio	^5.4.0	Asynchronous REST networking layer with interceptors
Data Immutability	Freezed & JSON Serializable	^2.4.7 / ^6.7.1	Code generation for immutable models and JSON mapping
Database	Cloud Firestore	^6.1.2	Real-time document persistence for project records
Authentication	Firebase Auth	^6.1.4	Email/Password and Google Sign-In authentication
Storage	Firebase Storage	^13.0.6	Cloud storage for project archive files
Backend Service	FastAPI (Python)	>=0.100.0	Asynchronous microservice for code analysis
Web Server	Uvicorn	>=0.20.0	Production ASGI web server
Web Scraper	BeautifulSoup4	^4.12.0	Web scraper for official Flutter breaking changes

---

Project Structure

NOVA Ecosystem
├── nova/                                   # Flutter Client Application
│   ├── config/                             # Environment Definitions
│   │   ├── dev.json                        # Development Config (API_BASE_URL)
│   │   └── prod.json                       # Production Config
│   ├── lib/
│   │   ├── config/                         # Environment Provider (AppConfig)
│   │   ├── models/                         # Domain Models & Freezed Generators
│   │   │   ├── analysis_result.dart
│   │   │   ├── analysis_result.freezed.dart
│   │   │   ├── analysis_result.g.dart
│   │   │   ├── flutter_project.dart
│   │   │   ├── flutter_project.freezed.dart
│   │   │   └── flutter_project.g.dart
│   │   ├── providers/                      # Theme & Application State
│   │   ├── repositories/                   # Data Repositories
│   │   │   ├── analysis_repository.dart
│   │   │   └── project_repository.dart
│   │   ├── router/                         # Declarative Routes (AppRouter)
│   │   ├── screens/                        # Glassmorphic View Pages
│   │   │   ├── add_project_page.dart
│   │   │   ├── analysis_result_page.dart
│   │   │   ├── analyze_project_page.dart
│   │   │   ├── breaking_changes_page.dart
│   │   │   ├── desktop_shell.dart
│   │   │   ├── home_page.dart
│   │   │   ├── login_page.dart
│   │   │   ├── migration_guide_page.dart
│   │   │   ├── migration_history_page.dart
│   │   │   ├── profile_page.dart
│   │   │   ├── project_list_page.dart
│   │   │   └── signup_page.dart
│   │   ├── services/                       # Services Layer
│   │   │   ├── analysis_service.dart
│   │   │   ├── api_client.dart
│   │   │   ├── auth_service.dart
│   │   │   ├── backend_health_service.dart
│   │   │   └── project_service.dart
│   │   ├── theme/                          # Design System Tokens & Glass Components
│   │   │   └── app_theme.dart
│   │   └── widgets/                        # Reusable Glass Widgets & Diff Viewer
│   │       ├── diff_viewer_widget.dart
│   │       └── sky_background.dart
│   ├── test/                               # Comprehensive Automated Test Suite
│   │   ├── models/                         # Model Deserialization & Fallback Tests
│   │   ├── screens/                        # Screen Integration Tests
│   │   ├── services/                       # AuthService & API Tests
│   │   └── widget_test.dart                # GlassCard Smoke Tests
│   ├── firestore.rules                     # Production Firestore Security Rules
│   └── storage.rules                       # Production Cloud Storage Security Rules
│
└── nova_analyzer_backend/                  # Python FastAPI Backend Engine
    ├── main.py                             # Analysis, Refactoring & Download Endpoints
    ├── scraper.py                          # Official Flutter Release Scraper
    └── requirements.txt                    # Python Dependency Manifest

---

Installation & Setup Guide

Prerequisites

• Flutter SDK: Version >=3.19.0
• Python: Version >=3.11
• Git: Installed and configured

---

Step 1: Clone the Repository

git clone https://github.com/jeswinbenedict/nova.git
cd nova

---

Step 2: Initialize & Launch Python FastAPI Backend

Navigate to the nova_analyzer_backend directory, activate the Python environment, install required dependencies, and launch Uvicorn:

cd nova_analyzer_backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload

The FastAPI backend service will start on http://localhost:8000.

---

Step 3: Configure & Launch Flutter Web Client

Open a second terminal window, navigate to the nova client directory, fetch packages, and run the development server pointing to your environment config:

cd nova
flutter pub get
flutter run -d web-server --web-port 3000 --dart-define-from-file=config/dev.json

Access the NOVA Web Client console in your browser at http://localhost:3000.

---

Environment Configuration

NOVA utilizes compile-time environment variables defined via external JSON configuration files (--dart-define-from-file).

Development Configuration (config/dev.json)

{
  "API_BASE_URL": "http://localhost:8000"
}

Production Configuration (config/prod.json)

{
  "API_BASE_URL": "https://api.nova.dev"
}

---

API Specifications & Endpoints

Endpoint	Method	Request Payload	Response / Output	Description
/	GET	None	{"status": "...", "version": "..."}	Backend health check
/live-breaking-changes	GET	None	{"source": "...", "changes": [...]}	Live scraped Flutter breaking changes
/analyze	POST	Multipart Form: zipFile, projectId, userId, projectName, flutterVersion	AnalysisResult JSON Document	Parses zip archive, executes AST refactoring, persists results to Firestore
/download-fixed/{projectId}	GET	projectId path parameter	Binary Zip File Stream	Streams the auto-refactored Flutter project archive

---

Data Models & Code Generation

NOVA models use Freezed and JSON Serializable for type safety, immutability, copy functionality (copyWith), and seamless JSON conversion.

Code Generation Workflow

To regenerate Freezed and JSON serialization files after modifying domain models:

flutter pub run build_runner build --delete-conflicting-outputs

---

Security Rules

Firestore Security Rules (firestore.rules)

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /projects/{projectId} {
      allow read, write: if request.auth != null && request.auth.uid == resource.data.userId;
      allow create: if request.auth != null && request.auth.uid == request.resource.data.userId;
    }
    match /analysis_results/{analysisId} {
      allow read, write: if request.auth != null;
    }
  }
}

Cloud Storage Security Rules (storage.rules)

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /projects/{userId}/{allPaths=**} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

---

Verification & Automated Testing

NOVA features a unit and widget test suite covering model parsing, null safety, form validation, and service contracts.

Executing Static Code Analysis

flutter analyze

Executing Automated Test Suite

flutter test

---

Build & Production Deployment

To compile the Flutter Web application for production:

flutter build web --release --dart-define-from-file=config/prod.json

The optimized static production bundle will be generated in build/web, ready for deployment to Cloud Storage, Firebase Hosting, Vercel, or Nginx.

---

Licensing

Distributed under the MIT License. See LICENSE for further details.