# alstn113/fluffy architecture

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

- Interactive diagram: https://gitdiagram.com/alstn113/fluffy
- Repository: https://github.com/alstn113/fluffy

## Overview

Based on our analysis of the file tree and README, this project is an online exam platform (“플러피”) that enables users to create, manage, and take exams online. It’s implemented as a full-stack application with a clear separation between a backend server (built with Kotlin and Spring Boot) and a frontend web application (built with React using Vite, Tailwind CSS, and related libraries).

##### Project’s Main Components
- Backend Server: This component is found under the “server” directory. It includes:
– API controllers grouped by functionalities (e.g., authentication, exam management, comments, questions, submissions, reactions, OAuth2 integration, etc.).
– Domain, application, infrastructure, and UI (controller) layers following a layered, possibly Hexagonal or Domain-Driven design.
– Supporting infrastructure: persistence via PostgreSQL (with Flyway for migration), caching/locking with Redis/Redisson, AWS S3 for storage, and integration with external OAuth2 providers (GitHub, Google).
– Build and deployment scripts (Dockerfile, Gradle scripts, Docker Compose files) that are used within CI/CD workflows defined in GitHub Actions.
- Frontend Web Application: Located under the “web” directory. It is a React application featuring:
– Component directories for dashboards, exams, questions, analytics, submission views, etc.
– API client modules that call backend endpoints.
– State management through Zustand and data fetching using Tanstack Query.
– Deployment configurations for Vercel and build configurations via Vite.
- External Services and Infrastructure: Note integrations with AWS (EC2, RDS, ElastiCache, S3, CloudFront), OAuth2 providers for authentication, and possibly other third-party tools.

##### Relationships and Interactions
- End Users (clients) interact with the web frontend.
- The React-based frontend communicates with the backend via REST API calls.
- The backend exposes well-structured endpoints (documented in the README link to the API documentation) and orchestrates business logic.
- The service layers within the backend coordinate with the database (PostgreSQL) and cache/storage subsystems (Redis, AWS S3).
- OAuth2 authentication integration involves flows where the backend interacts with external OAuth2 providers (for GitHub and Google).
- CI/CD systems (Github Actions, Docker, and Gradle builds) automate build, test, and deployment pipelines.

##### Architectural Patterns and Principles
- Layered Architecture: The backend neatly separates domain logic, application services, and controllers (UI layer), which is evident from the package structure.
- Domain-Driven Design: The presence of “domain,” “application,” and “infra” packages suggests encapsulation of business rules and data integrity.
- RESTful Architecture: Communication between frontend and backend is based on REST APIs.
- Deployment and Containerization: The Dockerfile, Docker Compose files, and GitHub workflows signify container-based builds and deployments.
- Integration Patterns: The project uses REST Docs for documentation and Testcontainers for integration testing, ensuring reliable system behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User
    User["User/Browser"]:::external

    %% Frontend Subgraph
    subgraph "Web Frontend (React)"
        FE_Main["Frontend App (React, Vite, Tailwind, Zustand)"]:::frontend
        FE_Components["UI Components"]:::frontend
        FE_API["API Clients"]:::frontend
        FE_Config["Build & Config (Vite, Tailwind, Vercel)"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend Server (Kotlin, Spring Boot)"
        BE_Main["Backend Core"]:::backend
        BE_API["API Controllers (UI Layer)"]:::backend
        BE_App["Application Services"]:::backend
        BE_Domain["Domain Layer"]:::backend
        BE_Persistence["Persistence (PostgreSQL, Flyway)"]:::backend
        BE_Cache["Caching/Distributed Locking (Redis)"]:::backend
        BE_AWS["AWS S3 Integration"]:::backend
        BE_OAuth["OAuth2 Integration"]:::backend
        BE_Scripts["Build & Deployment Scripts"]:::backend
    end

    %% External Systems Subgraph
    subgraph "External Services"
        DB["PostgreSQL Database"]:::database
        Ext_Redis["Redis Cache"]:::database
        AWS_S3["AWS S3 & CloudFront"]:::external
        OAuth["OAuth2 Providers (GitHub,Google)"]:::external
    end

    %% CI/CD & DevOps Subgraph
    subgraph "CI/CD & DevOps"
        CICD["CI/CD Pipeline (GitHub Actions)"]:::cicd
        Docker["Docker & Gradle Builds"]:::cicd
    end

    %% Connections for Frontend
    User -->|"accesses"| FE_Main
    FE_Config -->|"configures"| FE_Main
    FE_Main -->|"renders UI; calls API"| FE_API

    %% Frontend to Backend
    FE_Main -->|"REST calls"| BE_Main
    FE_API -->|"sends requests"| BE_API

    %% Backend internal flow
    BE_Main -->|"routes to"| BE_API
    BE_API -->|"delegates to"| BE_App
    BE_App -->|"executes business logic"| BE_Domain
    BE_App -->|"persists data"| BE_Persistence
    BE_App -->|"caches responses"| BE_Cache
    BE_App -->|"handles auth"| BE_OAuth
    BE_AWS -->|"stores files"| AWS_S3

    %% Backend to External Systems
    BE_Persistence -->|"read/write operations"| DB
    BE_Cache -->|"cache ops"| Ext_Redis
    BE_OAuth -->|"authenticates with"| OAuth

    %% CI/CD and Build Scripts connections
    BE_Scripts -->|"triggers"| CICD
    BE_Scripts -->|"builds via"| Docker

    %% Click Events
    click BE_Main "https://github.com/alstn113/fluffy/tree/main/server/"
    click BE_API "https://github.com/alstn113/fluffy/blob/main/server/src/main/kotlin/com/fluffy/auth/ui/AuthController.kt"
    click BE_Domain "https://github.com/alstn113/fluffy/tree/main/server/src/main/kotlin/com/fluffy/auth/domain"
    click BE_App "https://github.com/alstn113/fluffy/tree/main/server/src/main/kotlin/com/fluffy/auth/application"
    click BE_Persistence "https://github.com/alstn113/fluffy/tree/main/server/src/main/resources/db/migration"
    click BE_Cache "https://github.com/alstn113/fluffy/tree/main/server/src/main/kotlin/com/fluffy/infra/redis"
    click BE_AWS "https://github.com/alstn113/fluffy/tree/main/server/src/main/kotlin/com/fluffy/infra/storage"
    click BE_OAuth "https://github.com/alstn113/fluffy/tree/main/server/src/main/kotlin/com/fluffy/oauth2/"
    click BE_Scripts "https://github.com/alstn113/fluffy/tree/main/server/Dockerfile"
    click CICD "https://github.com/alstn113/fluffy/tree/main/.github/workflows"
    click FE_Main "https://github.com/alstn113/fluffy/tree/main/web/"
    click FE_Components "https://github.com/alstn113/fluffy/tree/main/web/src/components"
    click FE_API "https://github.com/alstn113/fluffy/tree/main/web/src/api"
    click FE_Config "https://github.com/alstn113/fluffy/blob/main/web/vite.config.ts"

    %% Class Styles
    classDef frontend fill:#ffdead,stroke:#8b4513,stroke-width:2px;
    classDef backend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef database fill:#98fb98,stroke:#2e8b57,stroke-width:2px;
    classDef external fill:#ffe4e1,stroke:#ff4500,stroke-width:2px;
    classDef cicd fill:#d3d3d3,stroke:#696969,stroke-width:2px;
    classDef externalService fill:#ffe4e1,stroke:#ff4500,stroke-width:2px;
```
