# abhi-kr-2100/lingetic architecture

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

- Interactive diagram: https://gitdiagram.com/abhi-kr-2100/lingetic
- Repository: https://github.com/abhi-kr-2100/lingetic

## Overview

##### Main Components
- Frontend (lingetic-nextjs-frontend): This uses Next.js (a React framework) and includes a well-organized pages, components, and test directories. It handles user interaction, language components (like LanguageCard, NavBar, and various question components), authentication buttons, and dynamic language pages for learning.
- Backend (lingetic-spring-backend): This is a Spring Boot application built in Java (using Gradle/Kotlin build scripts). Its structure is clearly divided into controllers (e.g., QuestionsController for HTTP endpoints), service/use-case layers (e.g., AttemptQuestionUseCase, TakeRegularTestUseCase), data access repositories (with Postgres repositories), DTOs for data transfer, and domain entities including question models, attempt statuses, and language models.
- Supporting Scripts and Tools: There is a separate scripts directory with Python scripts for utilities like filtering sentences, processing PDFs, converting images and generating/inserting questions. These can be used for data pre-processing, batch operations, or auxiliary tasks.
- Infrastructure & Configuration: There are important configuration files (Dockerfile, docker-compose.yml, .env.example, shell.nix) that support containerization, environment configuration, CI workflows (GitHub workflows), linter setups, and testing utilities (Jest configurations on the frontend, Gradle test setups on the backend).

##### Relationships & Interactions
- The Frontend interfaces with the Backend via REST API calls. The QuestionsController in the backend exposes endpoints that the Next.js frontend can consume, probably for fetching questions, submitting answers, and managing user progress.
- The Backend is architected using layered principles: HTTP Layer (Controllers) → Use Cases (service layer where business logic resides) → Repositories (for persisting/fetching information in a Postgres database).
- The Python scripts serve as auxiliary components – they may be scheduled or triggered separately to process data, manage images and sentences, and update the backend’s database.
- Environment-specific configurations (present via .env and Docker files) ensure consistent deployment, whether in local development or production.

##### Architectural Patterns
- Separation of concerns: The clear split between frontend and backend means that user interface logic is completely separated from business logic and persistence.
- MVC-like layering (in the Spring Boot backend): Controllers (HTTP), Services/UseCases (business logic), and Repositories (data access).
- Microservice integration principles: Even though this is a single project, the loosely coupled nature between the UI and backend and the script-based tooling suggests that any future expansion could adopt microservices if needed.
- Testing emphasis: Both parts include a comprehensive set of tests (Next.js using Jest and Java tests for the backend) to verify individual components and integration behavior.

##### Relevant Technologies
- Frontend: Next.js (React), Tailwind CSS (as indicated by tailwind.config.ts), and standard testing libraries (Jest, likely React Testing Library).
- Backend: Java with Spring Boot, Gradle build scripts, and integration with Postgres (as seen by Postgres repositories and migration scripts).
- Auxiliary: Python scripts for processing and data management.
- CI/CD/DevOps: GitHub workflows for code quality (qodana_code_quality.yml), Docker configuration files, and environment management (.env, shell.nix).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD & Config"
        cicd["CI/CD & Quality"]:::cicd
        config["Config & Deployment"]:::cicd
        dbm["DB Migration"]:::cicd
    end

    subgraph "Frontend Layer"
        fe["Frontend (Next.js)"]:::frontend
    end

    subgraph "Backend Layer"
        backend["Backend (Spring Boot)"]:::backend
        qc["QuestionsController"]:::backend
        uc["Service/Use Case Layer"]:::backend
        repo["Data Access Repositories"]:::backend
        entities["Domain Entities & DTOs"]:::backend
        auth["Authentication & Security"]:::backend
    end

    subgraph "Database Layer"
        db(("Postgres Database")):::database
    end

    subgraph "Auxiliary Scripts"
        aux["Python Scripts"]:::auxiliary
    end

    %% CI/CD & Config to Frontend and Backend
    cicd --> fe
    config --> backend
    dbm --> db

    %% Frontend calls Backend API (QuestionsController)
    fe -->|"APIcalls"| qc

    %% Backend internal flow
    qc -->|"calls"| uc
    qc -->|"authcheck"| auth
    uc -->|"uses"| entities
    uc -->|"invokes"| repo
    repo -->|"CRUD"| db

    %% Auxiliary Scripts interactions
    aux -->|"DataProcessing"| db
    aux -->|"Updates"| backend

    %% Click Events
    click fe "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-nextjs-frontend/"
    click backend "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-spring-backend/"
    click qc "https://github.com/abhi-kr-2100/lingetic/blob/main/lingetic-spring-backend/src/main/java/com/munetmo/lingetic/LanguageTestService/infra/HTTP/QuestionsController.java"
    click uc "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-spring-backend/src/main/java/com/munetmo/lingetic/LanguageTestService/UseCases/"
    click repo "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-spring-backend/src/main/java/com/munetmo/lingetic/LanguageTestService/Repositories/"
    click auth "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-spring-backend/src/main/java/com/munetmo/lingetic/infra/auth/"
    click cicd "https://github.com/abhi-kr-2100/lingetic/blob/main/.github/workflows/qodana_code_quality.yml"
    click config "https://github.com/abhi-kr-2100/lingetic/tree/main/lingetic-spring-backend/Dockerfile"
    click dbm "https://github.com/abhi-kr-2100/lingetic/blob/main/lingetic-spring-backend/src/main/resources/db/migration/V1__Create_Tables.sql"
    click aux "https://github.com/abhi-kr-2100/lingetic/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef auxiliary fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef cicd fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
