# nikk-666/solutionchallenge architecture

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

- Interactive diagram: https://gitdiagram.com/nikk-666/solutionchallenge
- Repository: https://github.com/nikk-666/solutionchallenge

## Overview

##### Main Components
- Frontend: This includes the user interface built with HTML, CSS, and JavaScript. The structure under the “frontend” directory shows multiple pages (index, login, signup, door, questions) and a rich interactive simulation component, with “src” organizing the game-like or simulation elements (scenes, entities, UI components) and “assets” storing maps and JSON configurations.
- Backend: Located under “backend”, this consists of the Flask application (app.py), model scripts (model.py, model_train.py), and supporting data/model files (career_model.csv, career_model.pkl). This layer is responsible for processing the psychological assessment inputs and initiating AI-driven career recommendations.
- Database & Cloud Services: According to the README, the project integrates with Firebase/Firestore and Google Cloud Services for hosting and data processing, even if the explicit configuration files for these are not visible.
- External AI Service: The integration with Gemini AI forms an external service piece that processes the recommendations.

##### Inter-Relationships
- The Frontend communicates with the Backend via HTTP requests (API endpoints hosted on Flask), sending user responses from assessment/questionnaire forms.
- The Backend processes these inputs using AI models (the trained model stored in career_model.pkl) and may perform further computations or data retrieval via Firebase/Firestore.
- The Backend then sends processed recommendations back to the Frontend.
- The Frontend uses its interactive scenes and UI components to display career simulation and recommendations; it utilizes libraries (such as kaboom.js indicated by kaboom.mjs) to provide dynamic visualizations and immersive interactions.
- External services such as Gemini AI are invoked by the Backend to enhance the recommendation capabilities.

##### Architectural Patterns and Design Principles
- Full-stack separation: A clear division between frontend (client-side interactive simulation and UI) and backend (API server with Flask logic and AI processing).
- Modular Design: The frontend is organized into modular components (scenes, entities, states, UI components), which aligns with modern front-end practices.
- Integration Points: The system has external connectivity with Google Cloud & Firebase and integration with Gemini AI.
- Data Flow: User inputs flow from the frontend to backend; AI processing and database accesses occur on the backend; recommendations are then delivered back to the frontend.

- Do the same for the Backend: API Server (Flask), Model Processing, and Data Handling.
- Annotations or legends to explain architectural patterns (modular design, separation of concerns) and the key technologies (Flask, Firebase, Gemini AI, kaboom.js).

Happy Diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        %% HTML Pages Cluster
        subgraph "Main HTML Pages"
            HTML1["index.html"]:::frontend
            HTML2["login.html"]:::frontend
            HTML3["signup.html"]:::frontend
            HTML4["door.html"]:::frontend
            HTML5["questions.html"]:::frontend
        end
        %% Simulation Assets Cluster
        subgraph "Simulation Assets"
            Scenes["Interactive Scenes"]:::frontend
            Entities["Game Entities"]:::frontend
            UI["UI Components"]:::frontend
            Content["Content & Dialogue"]:::frontend
            KaboomCtx["Kaboom Context"]:::frontend
            KaboomLib["Kaboom Library"]:::frontend
            GlobalState["Global State"]:::frontend
            Configs["Simulation & Configs"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend"
        Flask["Flask API Server"]:::backend
        subgraph "Model Processing"
            ModelScript["Model Script"]:::backend
            TrainScript["Train Script"]:::backend
            DataCSV["Data CSV"]:::backend
            ModelFile["Model File"]:::backend
        end
    end

    %% External Services Layer
    subgraph "External Services"
        Gemini["Gemini AI Service"]:::external
        Firebase["Firebase/Firestore & GoogleCloud"]:::external
    end

    %% Inter-Component Relationships
    %% Frontend HTML Pages send user input to Backend API Server
    HTML1 -->|"sendsInput"| Flask
    HTML2 -->|"sendsInput"| Flask
    HTML3 -->|"sendsInput"| Flask
    HTML4 -->|"sendsInput"| Flask
    HTML5 -->|"sendsInput"| Flask

    %% Backend processing flows
    Flask -->|"triggers"| ModelScript
    Flask -->|"invokes"| Gemini
    Flask -->|"accesses"| Firebase
    ModelScript -->|"utilizes"| DataCSV
    ModelScript -->|"utilizes"| ModelFile

    %% Backend response flows to Frontend Simulation Assets
    Flask -->|"returnsResult"| Scenes
    Scenes -->|"updatesVisuals"| Entities
    Scenes -->|"updatesUI"| UI

    %% Click Events for Frontend HTML Pages
    click HTML1 "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/index.html"
    click HTML2 "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/login.html"
    click HTML3 "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/signup.html"
    click HTML4 "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/door.html"
    click HTML5 "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/questions.html"

    %% Click Events for Simulation Assets
    click Scenes "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/src/scenes"
    click Entities "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/src/entities"
    click UI "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/src/uiComponents"
    click Content "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/src/content"
    click KaboomCtx "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/src/kaboomContext.js"
    click KaboomLib "https://github.com/nikk-666/solutionchallenge/blob/main//frontend/lib/kaboom.mjs"
    click GlobalState "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/src/state"
    click Configs "https://github.com/nikk-666/solutionchallenge/tree/main//frontend/assets/maps"

    %% Click Events for Backend Components
    click Flask "https://github.com/nikk-666/solutionchallenge/blob/main//backend/app.py"
    click ModelScript "https://github.com/nikk-666/solutionchallenge/blob/main//backend/model.py"
    click TrainScript "https://github.com/nikk-666/solutionchallenge/blob/main//backend/model_train.py"
    click DataCSV "https://github.com/nikk-666/solutionchallenge/blob/main//career_model.csv"
    click ModelFile "https://github.com/nikk-666/solutionchallenge/blob/main//career_model.pkl"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
