# glenngenre/codecraft architecture

> Architecture diagram of the GitHub repository glenngenre/codecraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/glenngenre/codecraft
- Repository: https://github.com/glenngenre/codecraft

## Overview

##### Project Type and Purpose
- This is a full-stack, cross-platform (mobile + web) Flutter application named “codecraft.”
- It serves as an educational coding platform with two user roles: apprentices (learners) and mentors (instructors).
- The client is built in Flutter (Dart) and leverages Firebase services (Authentication, Firestore, Cloud Functions, Cloud Messaging) plus a possible external code-execution API.

##### Top-Level Architectural Components
a. Client (Flutter App)
- Platforms: Android, iOS (android/…), Web (web/…)
- Presentation Layer: Screens (lib/screens/…), Widgets (lib/widgets/…)
- State Management: Provider package (lib/providers/…)
- Business Logic Services: (lib/services/…) – e.g. AuthHelper, ChallengeService, CodeClashService, QuizService, SubmissionService
- Models: Domain objects (lib/models/…)
- Utilities & I/O Abstractions: FileIO, WebIO (lib/io/…), Utils (lib/utils/…)
- Parser: HTML parser for static pages (lib/parser/…)
- Assets: Animations, videos, quizzes, markdown pages (assets/…)

b. Backend (Firebase + Serverless)
- Authentication: Email/password/Google via Firebase Auth
- Database: Firestore (collections for users, challenges, quizzes, codeClashes, submissions, organisations)
- Cloud Functions (functions/index.js): Hosted JS functions for business-critical operations (e.g. invite workflow, leaderboard calculations, code clash matchmaking)
- Security & Indexes: firestore.rules, firestore.indexes.json
- Hosting & Messaging: Web static assets + firebase-messaging-sw.js

c. External Services
- (Optional) Third-party code execution engine (invoked via CodeExecutionProvider or via a Cloud Function)
- Analytics / Crashlytics (configured in firebase.json / google-services.json)

##### Relationships and Data Flows
- The Flutter UI dispatches user actions to Provider controllers → calls Service layer → interacts with Firebase Auth / Firestore SDK or invokes Cloud Functions endpoints.
- Firestore triggers can invoke Cloud Functions for side-effects or data aggregation.
- Cloud Functions may coordinate with external code execution APIs and persist results back to Firestore.
- Real-time updates: Firestore snapshot listeners push live data to Providers → update UI.
- Static assets (animations, quizzes, pages) are bundled in the app or fetched via HTTP from hosting.

##### Architectural Patterns & Design Principles
- Layered architecture:
- Presentation (Screens & Widgets)
- State Management (Providers)
- Services/Repositories (data access, business logic)
- Data Layer (Firestore, Cloud Functions, external APIs)
- Dependency injection via provider package.
- MVVM-style separation of UI and view logic.
- Serverless microservices (each Cloud Function as a micro-endpoint).
- Assets-first: markdown pages + JSON-driven content parsed at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Flutter App)"
        direction TB
        Main["main.dart"]:::client
        subgraph "UI Layer"
            direction TB
            Screens["Screens"]:::client
            Widgets["Widgets"]:::client
        end
        subgraph "State Management"
            direction TB
            QuizProv["QuizProvider"]:::client
            ClashProv["CodeClashProvider"]:::client
            ExecProv["CodeExecutionProvider"]:::client
            DebugProv["DebuggingChallengeProvider"]:::client
            InvProv["InvitationProvider"]:::client
            ThemeProv["ThemeProvider"]:::client
            ScreenProv["ScreenProvider"]:::client
        end
        subgraph "Service Layer"
            direction TB
            AuthSrv["AuthHelper"]:::client
            ChallSrv["ChallengeService"]:::client
            ClashSrv["CodeClashService"]:::client
            DebugSrv["DebuggingChallengeService"]:::client
            InvSrv["InvitationService"]:::client
            QuizSrv["QuizService"]:::client
            SubSrv["SubmissionService"]:::client
            DBHelper["DatabaseHelper"]:::client
        end
        subgraph "Data Models"
            direction TB
            UserMod["AppUser"]:::client
            ChalMod["Challenge"]:::client
            QuizMod["Quiz"]:::client
            SubMod["Submission"]:::client
            ClashMod["CodeClash"]:::client
            DebugMod["DebuggingChallenge"]:::client
            InvMod["Invitation"]:::client
            OrgMod["Organisation"]:::client
            TestMod["UnitTest/Input/Output"]:::client
            PageMod["Page"]:::client
        end
        subgraph "I/O Abstractions"
            direction TB
            FileIO["FileIO"]:::client
            WebIO["WebIO"]:::client
            IOFac["IO"]:::client
        end
        Parser["HTML/Markdown Parser"]:::client
        Utils["Utils"]:::client
        Assets["Assets"]:::client
    end

    %% Backend Layer
    subgraph "Serverless Backend (Firebase)"
        direction TB
        Auth["Authentication"]:::firebase
        Firestore["Firestore"]:::firebase
        subgraph "Cloud Functions"
            direction TB
            CFIndex["index.js"]:::firebase
        end
        Hosting["Hosting & Messaging"]:::firebase
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        CodeAPI["Code Execution API"]:::external
        Analytics["Analytics/Crashlytics"]:::external
    end

    %% Relationships
    Main -->|"/"| Screens
    Main -->|"/"| Widgets
    Screens -->|"dispatch actions"| QuizProv
    Widgets -->|"dispatch actions"| QuizProv
    QuizProv -->|"uses"| QuizSrv
    ClashProv -->|"uses"| ClashSrv
    ExecProv -->|"uses"| AuthSrv
    ExecProv -->|"uses"| DBHelper
    DebugProv -->|"uses"| DebugSrv
    InvProv -->|"uses"| InvSrv
    ThemeProv -->|"uses Utils"| Utils
    ScreenProv -->|"coordinates"| Screens

    QuizSrv -->|"Firestore SDK: getQuizzes()"| Firestore
    AuthSrv -->|"FirebaseAuth.signIn()"| Auth
    ChallSrv -->|"Firestore SDK: getChallenges()"| Firestore
    ClashSrv -->|"invokeFunction()"| CFIndex
    DebugSrv -->|"Firestore SDK"| Firestore
    InvSrv -->|"CloudFunction: inviteUser()"| CFIndex
    SubSrv -->|"Firestore SDK: addSubmission()"| Firestore
    DBHelper -->|"Firestore SDK"| Firestore

    Firestore -->|"onSnapshot()"| QuizProv
    Firestore -->|"onSnapshot()"| ClashProv
    Firestore -->|"onSnapshot()"| DebugProv

    CFIndex -->|"read/write"| Firestore
    CFIndex -->|"invoke"| CodeAPI
    CFIndex -->|"publish"| Analytics

    Assets -->|"bundled assets"| Screens

    %% Click Events
    click Main "https://github.com/glenngenre/codecraft/blob/main/lib/main.dart"
    click Screens "https://github.com/glenngenre/codecraft/tree/main/lib/screens/"
    click Widgets "https://github.com/glenngenre/codecraft/tree/main/lib/widgets/"
    click QuizProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/quiz_provider.dart"
    click ClashProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/code_clash_provider.dart"
    click ExecProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/code_execution_provider.dart"
    click DebugProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/debugging_challenge_provider.dart"
    click InvProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/invitation_provider.dart"
    click ThemeProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/theme_provider.dart"
    click ScreenProv "https://github.com/glenngenre/codecraft/blob/main/lib/providers/screen_provider.dart"
    click AuthSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/auth/auth_helper.dart"
    click ChallSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/challenge_service.dart"
    click ClashSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/code_clash_service.dart"
    click DebugSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/debugging_challenge_service.dart"
    click InvSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/invitation_service.dart"
    click QuizSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/quiz_service.dart"
    click SubSrv "https://github.com/glenngenre/codecraft/blob/main/lib/services/submission_service.dart"
    click DBHelper "https://github.com/glenngenre/codecraft/blob/main/lib/services/database_helper.dart"
    click UserMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/app_user.dart"
    click ChalMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/challenge.dart"
    click QuizMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/quiz.dart"
    click SubMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/submission.dart"
    click ClashMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/code_clash.dart"
    click DebugMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/debugging_challenge.dart"
    click InvMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/invitation.dart"
    click OrgMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/organisation.dart"
    click TestMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/unit_test.dart"
    click TestMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/expected_output.dart"
    click TestMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/input.dart"
    click PageMod "https://github.com/glenngenre/codecraft/blob/main/lib/models/page.dart"
    click FileIO "https://github.com/glenngenre/codecraft/blob/main/lib/io/file_io.dart"
    click WebIO "https://github.com/glenngenre/codecraft/blob/main/lib/io/web_io.dart"
    click IOFac "https://github.com/glenngenre/codecraft/blob/main/lib/io/io.dart"
    click Parser "https://github.com/glenngenre/codecraft/blob/main/lib/parser/html_parser.dart"
    click Utils "https://github.com/glenngenre/codecraft/blob/main/lib/utils/utils.dart"
    click Assets "https://github.com/glenngenre/codecraft/tree/main/assets/"
    click Auth "https://github.com/glenngenre/codecraft/blob/main/firebase.json"
    click Firestore "https://github.com/glenngenre/codecraft/blob/main/firestore.rules"
    click CFIndex "https://github.com/glenngenre/codecraft/blob/main/functions/index.js"
    click Hosting "https://github.com/glenngenre/codecraft/blob/main/web/firebase-messaging-sw.js"
    click CodeAPI "https://github.com/glenngenre/codecraft/blob/main/lib/services/code_execution_service.dart"
    click Analytics "https://github.com/glenngenre/codecraft/blob/main/firebase.json"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef firebase fill:#FFE1B3,stroke:#d69e26,stroke-width:2px
    classDef external fill:#D6F5D6,stroke:#28a745,stroke-width:2px
```
