# vankhanhanny/gnec architecture

> Architecture diagram of the GitHub repository vankhanhanny/gnec, 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/vankhanhanny/gnec
- Repository: https://github.com/vankhanhanny/gnec

## Overview

##### Main Components
- Frontend (Next.js + TypeScript)
- Backend REST API (NestJS + Prisma + PostgreSQL)
- ASL Service (FastAPI + WebSockets + ML inference)
- AI Component (Python scripts + model training)
- External Services: Clerk (auth), Google Gemini API (sentence analysis)
- Database: PostgreSQL
- Deployment/orchestration: Docker-Compose

##### Relationships and Data Flows
- User’s Browser ↔ Frontend: HTTP/HTTPS, React UI interactions
- Frontend ↔ Backend API: REST calls for user data, job search, profile, guarded by Clerk tokens
- Frontend ↔ ASL Service: WebSocket for live video frames → inference results streamed back
- Backend ↔ Database: Prisma ORM generates SQL queries → PostgreSQL
- ASL Service ↔ AI Models: loads PyTorch models from filesystem, runs inference
- ASL Service ↔ Google Gemini: HTTP API calls for sentence analysis
- AI Component (training notebooks, scripts) is offline/development: accesses raw videos, trains models, outputs to models directory

##### Architectural Patterns
- Microservices: Backend API and ASL Service are separate containers/processes
- Layered architecture in Backend: Controllers → Services → Repositories → Prisma → Database
- Frontend: “app” directory and UI component library (atomic/ui-layout components)
- Real-time streaming with WebSockets in ASL Service
- External auth integration (Clerk strategy in NestJS and Next.js middleware)

##### Technologies & Frameworks
- Frontend: Next.js, React, TypeScript, Clerk SDK, Tailwind CSS (postcss.config)
- Backend: NestJS, TypeScript, Prisma, PostgreSQL, Clerk Guard
- ASL Service: Python, FastAPI, WebSockets (starlette), PyTorch models, Google Gemini API
- AI Component: Python Jupyter notebooks, OpenCV (or similar), PyTorch, LSTM/CNN models
- Orchestration: Docker/Docker-Compose, virtual environments for Python services

- Notes on ports (e.g., Frontend:3000, Backend:5000, ASL:8000)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Next.js Frontend" 
        direction TB
        AppDir["app Directory"]:::frontend
        Components["UI Components"]:::frontend
        LibAPI["api.ts"]:::frontend
        LibAuth["auth.ts"]:::frontend
        LibJob["jobSearchApi.ts"]:::frontend
        Middleware["middleware.ts"]:::frontend
    end

    %% Backend and ASL side by side
    subgraph Backend_and_ASL
        direction TB
        subgraph "NestJS Backend API"
            direction TB
            BEMain["main.ts & app.module.ts"]:::backend
            AppCtrl["app.controller.ts"]:::backend
            AppSvc["app.service.ts"]:::backend

            subgraph AuthModule
                direction TB
                AuthMod["auth.module.ts"]:::backend
                ClerkStrat["clerk.strategy.ts"]:::backend
                ClerkGuard["clerk-auth.guard.ts"]:::backend
            end

            subgraph UsersModule
                direction TB
                UsersMod["users.module.ts"]:::backend
                UsersCtrl["users.controller.ts"]:::backend
                UsersSvc["users.service.ts"]:::backend
                UsersRepo["users.repository.ts"]:::backend
            end

            subgraph JobSearchModule
                direction TB
                JSMod["job-search.module.ts"]:::backend
                JSCtrl["job-search.controller.ts"]:::backend
                JSSvc["job-search.service.ts"]:::backend
            end

            subgraph "Prisma & Database Layer"
                direction TB
                Schema["schema.prisma"]:::backend
                Migrations["migrations/"]:::backend
                PrismaMod["prisma.module.ts"]:::backend
                PrismaSvc["prisma.service.ts"]:::backend
                BaseRepo["base.repository.ts"]:::backend
                BaseSvc["base.service.ts"]:::backend
            end
        end

        subgraph "FastAPI ASL Service"
            direction TB
            ASLMain["main.py & run.py"]:::asl
            Inference["asl_recognizer.py"]:::asl
            GeminiInt["analyze_gemini.py"]:::asl
            DockerASL["Dockerfile & requirements"]:::asl
        end
    end

    %% Database and Model Storage
    DB["PostgreSQL Database"]:::database
    ModelStorage["Model Storage (ai/models)"]:::asl

    %% AI Component
    AIComp["AI Training & Notebooks"]:::ai

    %% External Services
    Clerk["Clerk Auth Service"]:::external
    Gemini["Google Gemini API"]:::external

    %% Orchestration
    DockerCompose["docker-compose.yml"]:::external

    %% Connections
    User -->|"HTTP/HTTPS"| AppDir
    AppDir -->|"uses components"| Components
    AppDir -->|"calls"| LibAPI
    AppDir -->|"calls"| LibAuth
    AppDir -->|"calls"| LibJob
    AppDir -->|"injects"| Middleware

    AppDir -->|"REST API"| BEMain
    Components -->|"REST API"| BEMain

    AppDir -->|"<--> WebSocket"| ASLMain

    BEMain -->|"guards"| Clerk
    BEMain -->|"Prisma ORM"| Schema
    BEMain -->|"SQL"| DB

    ASLMain -->|"loads models"| ModelStorage
    ASLMain -->|"HTTP"| Gemini

    AIComp -.->|"outputs models"| ModelStorage

    Clerk -->|"OAuth tokens"| AppDir
    Clerk -->|"OAuth tokens"| BEMain

    DockerCompose -->|deploys| AppDir
    DockerCompose -->|deploys| BEMain
    DockerCompose -->|deploys| ASLMain

    %% Click Events Frontend
    click AppDir "https://github.com/vankhanhanny/gnec/tree/main/gnec_frontend/src/app/"
    click Components "https://github.com/vankhanhanny/gnec/tree/main/gnec_frontend/src/components/"
    click LibAPI "https://github.com/vankhanhanny/gnec/blob/main/gnec_frontend/src/lib/api.ts"
    click LibAuth "https://github.com/vankhanhanny/gnec/blob/main/gnec_frontend/src/lib/auth.ts"
    click LibJob "https://github.com/vankhanhanny/gnec/blob/main/gnec_frontend/src/lib/jobSearchApi.ts"
    click Middleware "https://github.com/vankhanhanny/gnec/blob/main/gnec_frontend/src/middleware.ts"

    %% Click Events Backend
    click BEMain "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/main.ts"
    click AppCtrl "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/app.controller.ts"
    click AppSvc "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/app.service.ts"
    click AuthMod "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/auth/auth.module.ts"
    click ClerkStrat "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/auth/clerk.strategy.ts"
    click ClerkGuard "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/auth/clerk-auth.guard.ts"
    click UsersMod "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/users/users.module.ts"
    click UsersCtrl "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/users/users.controller.ts"
    click UsersSvc "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/users/users.service.ts"
    click UsersRepo "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/users/users.repository.ts"
    click JSMod "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/job-search/job-search.module.ts"
    click JSCtrl "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/job-search/job-search.controller.ts"
    click JSSvc "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/job-search/job-search.service.ts"
    click Schema "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/prisma/schema.prisma"
    click Migrations "https://github.com/vankhanhanny/gnec/tree/main/gnec_hackathon/backend/prisma/migrations/"
    click PrismaMod "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/prisma/prisma.module.ts"
    click PrismaSvc "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/prisma/prisma.service.ts"
    click BaseRepo "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/database/base.repository.ts"
    click BaseSvc "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/src/database/base.service.ts"

    %% Click Events ASL Service
    click ASLMain "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/asl-service/main.py"
    click Inference "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/asl-service/asl_recognizer.py"
    click GeminiInt "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/backend/asl-service/analyze_gemini.py"
    click DockerASL "https://github.com/vankhanhanny/gnec/tree/main/gnec_hackathon/backend/asl-service/Dockerfile"

    %% Click Events AI Component
    click AIComp "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/ai/asl_alphabet.ipynb"
    click AIComp "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/ai/asl_alphabet_new.ipynb"
    click AIComp "https://github.com/vankhanhanny/gnec/blob/main/gnec_hackathon/ai/analyze_gemini.py"
    click AIComp "https://github.com/vankhanhanny/gnec/tree/main/gnec_hackathon/ai/raw_videos/"
    click AIComp "https://github.com/vankhanhanny/gnec/tree/main/gnec_hackathon/ai/annotated_videos/"
    click ModelStorage "https://github.com/vankhanhanny/gnec/tree/main/gnec_hackathon/ai/models/"

    %% Click Orchestration
    click DockerCompose "https://github.com/vankhanhanny/gnec/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef asl fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef database fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef ai fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#333,stroke-dasharray:5 5,stroke-width:1px
```
