# tejas05wini/career_simulation_sys architecture

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

- Interactive diagram: https://gitdiagram.com/tejas05wini/career_simulation_sys
- Repository: https://github.com/tejas05wini/career_simulation_sys

## Overview

##### Project Type and Purpose
- Full-stack web application (Next.js + TypeScript) with embedded AI logic and rule/ontology engines.
- Purpose: Guide users through a simulated 10-year career path by combining user input, decision trees, rule-based matching, ontology lookups, and calls to Google’s Gemini AI.

##### Main Components
a. Client / Browser
– Next.js 13 “app” directory delivers React pages (app/layout.tsx, app/page.tsx).
– UI Components (components/ui/* and domain-specific components like career-matching.tsx, decision-tree.tsx).
b. Next.js Server / API Layer
– Server-Side Rendering (SSR) / Routing (app/page.tsx, app/layout.tsx).
– Serverless function: `app/api/gemini/route.ts` handles HTTP requests to our Gemini API client (lib/gemini-client.ts).
c. Business Logic Layer (Backend Utility Modules)
– Rule Engine (utils/career-matching.ts, rule-based logic in utils and Python scripts).
– Decision-Tree logic (components/decision-tree.tsx and possibly enhanced_simulation.py for advanced algorithms).
– Ontology-Based Matching (data/career-ontology.json + utils/ontology-map.ts).
– Report Generation (utils/report-generator.ts and template_generator.py for .txt outputs).
d. External AI Service
– Google Gemini API (accessed via lib/gemini-client.ts).
e. Data Layer
– JSON files (data/career-ontology.json).
– Potential file-based storage (.txt reports).
– No centralized DB—uses in-repo JSON and ephemeral state in memory or serverless functions.
f. Static Assets & Styling
g. Auxiliary Scripts (Offline/Microservice)
– statistical_model.py, enhanced_simulation.py, template_generator.py—can be represented as separate batch jobs or microservices that preprocess data or generate advanced simulations.

##### Relationships & Data Flow
- User interacts with the Browser UI → submits form (user-input-form.tsx) → request to Next.js API or page route.
- Next.js API (route.ts) orchestrates:
1. Validate input → forward to Rule Engine (utils/reporter, utils/career-matching).
2. Lookup ontology (data/career-ontology.json).
3. Call Gemini API (lib/gemini-client.ts) for narrative generation.
4. Post-process with Decision Tree logic.
5. Package results → return JSON response.
- Frontend consumes the response → updated simulation-results.tsx, enhanced-simulation-results.tsx.
- User can trigger report download → Report Generator creates .txt via template_generator.py or client-side download utility.

##### Architectural Patterns & Principles
– Separation of concerns: UI layer (React), API layer (Next.js serverless), business logic modules (utils + Python).
– Serverless functions for easy scaling of the AI call.
– Modular, file-based “data store” using JSON and Python scripts for offline analytics.
– Layered design: Presentation → API → Business Logic → Data/External Services.

a. Components & Layout
1. Top row “Clients”: Browser / Mobile App
2. Middle row “Frontend”: Next.js React Pages & Components
3. Middle row “API Layer”: Next.js Serverless Routes
4. Lower row “Business Logic”: Rule Engine, Ontology Service, Decision-Tree Module, Report Generator
5. External block “Gemini AI” (external)
6. Data block “Career Ontology JSON”
7. Optional block “Python Batch Services” (statistical_model.py, enhanced_simulation.py)
– Blue rectangles for UI components.
– Green for serverless/API modules.
– Orange for core logic engines.
– Gray for external services (Gemini AI).

– Clear labels: e.g., “Next.js Serverless API (/api/gemini)”, “Rule Engine (utils/career-matching.ts)”.
– Call-out key technologies: Next.js, React, Tailwind CSS, Google Gemini API, JSON Ontology.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client / Browser"
        Browser["Browser / Client"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend (Next.js React)" 
        Layout["app/layout.tsx"]:::ui
        Page["app/page.tsx"]:::ui
        subgraph "UI Components" 
            CareerMatching["Career Matching"]:::ui
            DecisionTree["Decision Tree"]:::ui
            SimulationResults["Simulation Results"]:::ui
            EnhancedSimulationResults["Enhanced Simulation Results"]:::ui
            UserInputForm["User Input Form"]:::ui
        end
        subgraph "UI Library (Radix UI/Tailwind)" 
            UILib["components/ui/*"]:::ui
        end
    end

    %% API Layer
    subgraph "API Layer (Next.js Serverless)"
        GeminiAPI["Next.js Serverless API (/api/gemini)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        RuleEngine["Rule Engine (utils/career-matching.ts)"]:::logic
        DecisionTreeLogic["Decision-Tree Module"]:::logic
        OntologyService["Ontology Lookup (data/career-ontology.json)"]:::data
        ReportGenerator["Report Generator (utils/report-generator.ts)"]:::logic
    end

    %% Data & External Services
    subgraph "Data Layer"
        OntologyFile["career-ontology.json"]:::data
    end
    Gemini["Google Gemini AI"]:::external

    %% Auxiliary Scripts
    subgraph "Batch / Microservices (Python Scripts)"
        EnhancedSimScript["enhanced_simulation.py"]:::script
        StatisticalModel["statistical_model.py"]:::script
        TemplateGenerator["template_generator.py"]:::script
    end

    %% Static Assets & Styling
    subgraph "Static Assets & Styling"
        GlobalStyles["styles/globals.css / app/globals.css"]:::asset
        TailwindConfig["tailwind.config.ts"]:::asset
        PublicAssets["public/"]:::asset
    end

    %% Utility Helpers & Hooks
    subgraph "Utilities"
        Utils["lib/utils.ts"]:::logic
        Hooks["hooks/use-mobile.tsx, use-toast.ts"]:::ui
    end

    %% Connections
    Browser --> Layout
    Browser --> Page
    Layout --> CareerMatching
    Layout --> DecisionTree
    Layout --> SimulationResults
    Layout --> EnhancedSimulationResults
    Layout --> UserInputForm
    Layout --> UILib

    UserInputForm -->|submits data| GeminiAPI
    GeminiAPI -->|validate & route| RuleEngine
    GeminiAPI -->|lookup| OntologyService
    GeminiAPI -->|call| Gemini
    GeminiAPI -->|post-process| DecisionTreeLogic
    GeminiAPI -->|generate report| ReportGenerator
    RuleEngine --> OntologyFile
    OntologyService --> OntologyFile
    Gemini --> RuleEngine
    ReportGenerator --> TemplateGenerator

    GeminiAPI -->|response| SimulationResults
    GeminiAPI -->|response| EnhancedSimulationResults

    EnhancedSimScript --> OntologyFile
    StatisticalModel --> OntologyFile
    TemplateGenerator --> ReportGenerator

    %% Click Events
    click Layout "https://github.com/tejas05wini/career_simulation_sys/blob/main/app/layout.tsx"
    click Page "https://github.com/tejas05wini/career_simulation_sys/blob/main/app/page.tsx"
    click CareerMatching "https://github.com/tejas05wini/career_simulation_sys/blob/main/components/career-matching.tsx"
    click DecisionTree "https://github.com/tejas05wini/career_simulation_sys/blob/main/components/decision-tree.tsx"
    click SimulationResults "https://github.com/tejas05wini/career_simulation_sys/blob/main/components/simulation-results.tsx"
    click EnhancedSimulationResults "https://github.com/tejas05wini/career_simulation_sys/blob/main/components/enhanced-simulation-results.tsx"
    click UserInputForm "https://github.com/tejas05wini/career_simulation_sys/blob/main/components/user-input-form.tsx"
    click UILib "https://github.com/tejas05wini/career_simulation_sys/tree/main/components/ui/"
    click GeminiAPI "https://github.com/tejas05wini/career_simulation_sys/blob/main/app/api/gemini/route.ts"
    click RuleEngine "https://github.com/tejas05wini/career_simulation_sys/blob/main/utils/career-matching.ts"
    click ReportGenerator "https://github.com/tejas05wini/career_simulation_sys/blob/main/utils/report-generator.ts"
    click OntologyFile "https://github.com/tejas05wini/career_simulation_sys/blob/main/data/career-ontology.json"
    click EnhancedSimScript "https://github.com/tejas05wini/career_simulation_sys/blob/main/enhanced_simulation.py"
    click StatisticalModel "https://github.com/tejas05wini/career_simulation_sys/blob/main/statistical_model.py"
    click TemplateGenerator "https://github.com/tejas05wini/career_simulation_sys/blob/main/template_generator.py"
    click Utils "https://github.com/tejas05wini/career_simulation_sys/blob/main/lib/utils.ts"
    click Hooks "https://github.com/tejas05wini/career_simulation_sys/blob/main/hooks/use-mobile.tsx"
    click Hooks "https://github.com/tejas05wini/career_simulation_sys/blob/main/hooks/use-toast.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef api fill:#d4edda,stroke:#155724,color:#155724;
    classDef logic fill:#fff3cd,stroke:#856404,color:#856404;
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef script fill:#f0e6ff,stroke:#5f259f,color:#5f259f;
    classDef asset fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
