# thanhquang2004/study-tracker-genai architecture

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

- Interactive diagram: https://gitdiagram.com/thanhquang2004/study-tracker-genai
- Repository: https://github.com/thanhquang2004/study-tracker-genai

## Overview

##### Project Type & Purpose
- It’s a server-side application built on NestJS (Node.js + TypeScript).
- It exposes RESTful endpoints via controllers.
- It uses Prisma as an ORM to persist data in a relational database.
- It implements authentication (local/JWT + Google OAuth).
- It includes business modules: user management, roadmaps, and an AI-powered “gemini” module (quiz, question, roadmap generation).

##### File Structure & Patterns
Top‐level modules under src/:
– auth/ (controllers, services, guards, strategies, DTOs, decorator)
– user/ (controllers, services, entities, DTOs)
– roadmap/ (controllers, services, entities, DTOs)
– gemini/ (controllers, services, DTOs)
– prisma/ (PrismaModule & PrismaService)
Standard Nest layering: Controller → Service → (PrismaService → DB).
Guards & strategies for auth, DTOs for data validation, Entities for ORM mappings.

##### Core Components
- Client(s): web or mobile front-end (HTTP requests).
- API Layer (NestJS):
– Controllers (AuthController, UserController, RoadmapController, GeminiController)
– Services (AuthService, UserService, RoadmapService, GeminiService)
– Guards & Strategies (JWT, Local, Google)
- Persistence Layer:
– PrismaService & generated client
– Underlying SQL database (PostgreSQL, MySQL, etc.)
- External Services:
– Google OAuth / OpenID Connect (for social login)
– External AI/LLM API that “gemini” module calls (e.g., Google Gemini or OpenAI)

##### Relationships & Data Flows
- Client → HTTP Request → Controller
- Controller → Service (calls business logic)
- Service → PrismaService → Database (CRUD)
- AuthController → AuthService → JWT/Google Strategy → Token issuance/validation
- GeminiService → External AI API → Response → formatted DTO → Controller → Client

##### Important Architectural Patterns
- Modular monolith (single Nest application composed of coherent modules).
- Layered (Presentation → Business Logic → Data Access).
- Pluggable authentication via Guards + Strategies.
- DTOs for input/output validation.
- Dependency injection throughout (Nest’s @Injectable services).

- NestJS Application boundary containing all modules.
- Modules (Auth, User, Roadmap, Gemini) with their internal Controllers & Services.
- PrismaService as the shared data-access component.
- External Google OAuth service connected to AuthService/Strategy.
- External AI/LLM service connected to GeminiService.
– Client → Controller
– Controller → Service
– Service → PrismaService → DB
– Service → External AI / OAuth

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (Web/Mobile)"]:::external

    %% NestJS Application Boundary
    subgraph "NestJS Application"
        direction TB

        %% Entry Points
        main["src/main.ts\n(Main Entry)"]:::entry
        AppModule["AppModule"]:::module
        AppController["AppController"]:::controller
        AppService["AppService"]:::service

        %% Auth Module
        subgraph "Auth Module" 
            direction TB
            AuthController["AuthController"]:::controller
            AuthService["AuthService"]:::service
            authEntity["Auth Entity"]:::entity
            createAuthDto["CreateAuthDto"]:::dto
            currentUserDecorator["CurrentUser Decorator"]:::crosscut
            jwtGuard["JWT Guard"]:::guard
            localGuard["Local Guard"]:::guard
            googleGuard["Google OAuth Guard"]:::guard
            jwtStrategy["JWT Strategy"]:::strategy
            localStrategy["Local Strategy"]:::strategy
            googleStrategy["Google Strategy"]:::strategy
            serializer["Serializer"]:::strategy
        end

        %% User Module
        subgraph "User Module"
            direction TB
            userController["UserController"]:::controller
            userService["UserService"]:::service
            userEntity["User Entity"]:::entity
            createUserDto["CreateUserDto"]:::dto
            updateUserDto["UpdateUserDto"]:::dto
        end

        %% Roadmap Module
        subgraph "Roadmap Module"
            direction TB
            roadmapController["RoadmapController"]:::controller
            roadmapService["RoadmapService"]:::service
            roadmapEntity["Roadmap Entity"]:::entity
            createRoadmapDto["CreateRoadmapDto"]:::dto
            updateRoadmapDto["UpdateRoadmapDto"]:::dto
        end

        %% Gemini Module
        subgraph "Gemini Module"
            direction TB
            geminiController["GeminiController"]:::controller
            geminiService["GeminiService"]:::service
            generateQuizDto["GenerateQuizDto"]:::dto
            generateQuesDto["GenerateQuestionsDto"]:::dto
            generateRoadmapDto["GenerateRoadmapDto"]:::dto
        end

        %% Prisma Layer
        prismaModule["PrismaModule"]:::module
        prismaService["PrismaService"]:::service
    end

    %% Database
    DB["SQL Database"]:::database

    %% External Services
    GoogleOAuth["Google OAuth / OpenID Connect"]:::external
    AIService["External AI/LLM API"]:::external

    %% Request Flow
    Client -->|HTTP Request| AuthController
    Client -->|HTTP Request| userController
    Client -->|HTTP Request| roadmapController
    Client -->|HTTP Request| geminiController

    %% Controllers to Services
    AuthController -->|calls| AuthService
    userController -->|calls| userService
    roadmapController -->|calls| roadmapService
    geminiController -->|calls| geminiService

    %% Services to Prisma
    AuthService -->|uses| prismaService
    userService -->|uses| prismaService
    roadmapService -->|uses| prismaService
    geminiService -->|uses| prismaService

    %% Prisma to DB
    prismaService -->|CRUD| DB

    %% Auth Guards & Strategies
    AuthController -->|protected by| jwtGuard
    AuthController -->|protected by| localGuard
    AuthController -->|protected by| googleGuard
    AuthService -->|issues/validates| jwtStrategy
    AuthService -->|validates| localStrategy
    AuthService -->|validates| googleStrategy
    AuthService -->|serializes| serializer

    %% External Integrations
    AuthService -.->|OAuth flow| GoogleOAuth
    geminiService -.->|AI call| AIService

    %% NestJS Bootstrap Flow
    main --> AppModule
    AppModule --> AppController
    AppModule --> AppService

    %% Legend Classes
    classDef external fill:#AEDFF7,stroke:#333,stroke-width:1px;
    classDef entry fill:#FFF2CC,stroke:#D6A600,stroke-width:1px;
    classDef module fill:#D5E8D4,stroke:#82B366,stroke-width:1px;
    classDef controller fill:#FFF2CC,stroke:#B8860B,stroke-width:1px;
    classDef service fill:#E1D5E7,stroke:#9673A6,stroke-width:1px;
    classDef entity fill:#F8CECC,stroke:#B85450,stroke-width:1px;
    classDef dto fill:#DAE8FC,stroke:#6C8EBF,stroke-width:1px;
    classDef guard stroke-dasharray: 5 5,stroke:#D6A600,fill:none;
    classDef strategy stroke-dasharray: 5 5,stroke:#B45F06,fill:none;
    classDef crosscut stroke-dasharray:4 2,stroke:#333,fill:none;

    %% Click Events
    click main "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/main.ts"
    click AppModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/app.module.ts"
    click AppController "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/app.controller.ts"
    click AppService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/app.service.ts"

    click AuthModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/auth.module.ts"
    click AuthController "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/auth.controller.ts"
    click AuthService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/auth.service.ts"
    click authEntity "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/entities/auth.entity.ts"
    click createAuthDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/dto/create-auth.dto.ts"
    click currentUserDecorator "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/decorator/current-user.decorator.ts"
    click jwtGuard "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/guards/jwt-auth.guard.ts"
    click localGuard "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/guards/local-auth.guard.ts"
    click googleGuard "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/guards/google-auth.guard.ts"
    click jwtStrategy "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/strategies/jwt.strategy.ts"
    click localStrategy "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/strategies/local.strategy.ts"
    click googleStrategy "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/strategies/google.strategy.ts"
    click serializer "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/auth/strategies/Serializer.ts"

    click userModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/user.module.ts"
    click userController "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/user.controller.ts"
    click userService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/user.service.ts"
    click userEntity "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/entities/user.entity.ts"
    click createUserDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/dto/create-user.dto.ts"
    click updateUserDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/user/dto/update-user.dto.ts"

    click roadmapModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/roadmap.module.ts"
    click roadmapController "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/roadmap.controller.ts"
    click roadmapService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/roadmap.service.ts"
    click roadmapEntity "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/entities/roadmap.entity.ts"
    click createRoadmapDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/dto/create-roadmap.dto.ts"
    click updateRoadmapDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/roadmap/dto/update-roadmap.dto.ts"

    click geminiModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/gemini.module.ts"
    click geminiController "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/gemini.controller.ts"
    click geminiService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/gemini.service.ts"
    click generateQuizDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/dto/generateQuiz.dto.ts"
    click generateQuesDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/dto/generate-ques.dto.ts"
    click generateRoadmapDto "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/gemini/dto/generate-roadmap.dto.ts"

    click prismaModule "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/prisma/prisma.module.ts"
    click prismaService "https://github.com/thanhquang2004/study-tracker-genai/blob/main/src/prisma/prisma.service.ts"
    click prismaSchema "https://github.com/thanhquang2004/study-tracker-genai/blob/main/prisma/schema.prisma"
```
