# princepal9120/aniverse architecture

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

- Interactive diagram: https://gitdiagram.com/princepal9120/aniverse
- Repository: https://github.com/princepal9120/aniverse

## Overview

##### Project type and purpose
- Aniverese is a full-stack web application:
- A React.js single-page application (“client” folder)
- A Go-based RESTful backend (“server” folder)
- A MongoDB database for storage
- Integration with OpenAI and LangChain Go for AI-driven recommendations
- Purpose: deliver personalized anime recommendations via an AI pipeline.

##### File structure
- Top-level split: “client” (frontend) and “server” (backend).
- client/: standard React + Vite project; components/, hooks/, contexts/, pages/, UI primitives.
- server/: Go module with cmd/server (entrypoint), internals/ containing controllers, models, routes, middleware, databaseConnection, utils, and seed scripts.
- Docker files (dockerfile, dockerfile.dev, docker-compose.yml) suggest containerized deployment.
- Configuration: .env in client, .air.toml for live reload, Docker config, Go modules.

##### README for additional insights
- Uses RESTful API, MongoDB, LangChain Go library, OpenAI API.
- Results: 40% engagement boost, 25% content consumption increase.
- Future enhancements: collaborative filtering, analytics dashboard.

a. Main components
1. Client (React SPA)
2. API Gateway / Go REST server
3. Controllers & Services (AI orchestration via LangChain Go + OpenAI)
4. MongoDB database
5. External service: OpenAI API
6. (Optional) Docker / Kubernetes layer for deployment

b. Relationships & interactions
- User ↔ React UI
- React UI → Go API (HTTP/JSON)
- API → Controllers → Services →
- AI pipeline (LangChain Go invoking OpenAI)
- Database CRUD (MongoDB)
- Services → return JSON → frontend
- Authentication: AuthMiddleware intercepts requests; tokenUtil interacts with JWT/OAuth.
- Seed scripts → initialize MongoDB with sample data.

c. Architectural patterns & design principles
- Separation of concerns: UI layer, API layer, data layer, AI service layer.
- Modular design: routes separate protected/unprotected; controllers per resource; middleware for cross-cutting concerns.
- Containerization: Docker images, docker-compose orchestration.
- Asynchronous AI calls encapsulated in service modules.

d. Key technologies/frameworks
- React.js + Vite + Tailwind CSS / UI primitives
- TypeScript
- Golang 1.22
- LangChain Go
- OpenAI GPT API
- MongoDB
- Docker

##### Detailed component breakdown
- client/src/components & pages (grouped under “UI Layer”)
- AuthContext, FavoriteContext (State management)
- ProtectedRoute component (access control in UI)
- server/cmd/server/main.go (app entrypoint)
- internals/routes (API routing layer)
- internals/controllers (business logic)
- internals/utils/tokenUtil.go (JWT handling)
- internals/database/databaseConnection.go (MongoDB connection)
- internals/seed (data initialization)
- Docker Compose network linking MongoDB and Go service

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser(["Browser"]):::external
    ReactSPA["React SPA\nclient/src/main.tsx"]:::frontend
    click ReactSPA "https://github.com/princepal9120/aniverse/blob/main/client/src/main.tsx"
    
    subgraph "UI Layer"
        Components["Components\nclient/src/components/"]:::frontend
        click Components "https://github.com/princepal9120/aniverse/tree/main/client/src/components/"
        Pages["Pages\nclient/src/pages/"]:::frontend
        click Pages "https://github.com/princepal9120/aniverse/tree/main/client/src/pages/"
        ProtectedRoute["ProtectedRoute\nclient/src/components/ProtectedRoute.tsx"]:::frontend
        click ProtectedRoute "https://github.com/princepal9120/aniverse/blob/main/client/src/components/ProtectedRoute.tsx"
        AuthContext["AuthContext\nclient/src/contexts/AuthContext.tsx"]:::frontend
        click AuthContext "https://github.com/princepal9120/aniverse/blob/main/client/src/contexts/AuthContext.tsx"
        FavoriteContext["FavoriteContext\nclient/src/contexts/FavoriteContext.tsx"]:::frontend
        click FavoriteContext "https://github.com/princepal9120/aniverse/blob/main/client/src/contexts/FavoriteContext.tsx"
        APIClient["API Client\nclient/src/lib/api.ts"]:::frontend
        click APIClient "https://github.com/princepal9120/aniverse/blob/main/client/src/lib/api.ts"
    end
    
    subgraph "Backend API Layer"
        APIGateway["Go REST API\nserver/cmd/server/main.go"]:::backend
        click APIGateway "https://github.com/princepal9120/aniverse/blob/main/server/cmd/server/main.go"
    
        subgraph "Routing Layer"
            Unprotected["Unprotected Routes\nserver/internals/routes/unprotectedRoutes.go"]:::backend
            click Unprotected "https://github.com/princepal9120/aniverse/blob/main/server/internals/routes/unprotectedRoutes.go"
            Protected["Protected Routes\nserver/internals/routes/protectedRoutes.go"]:::backend
            click Protected "https://github.com/princepal9120/aniverse/blob/main/server/internals/routes/protectedRoutes.go"
        end
    
        subgraph "Middleware"
            AuthMW["AuthMiddleware\nserver/internals/middleware/authMiddleware.go"]:::backend
            click AuthMW "https://github.com/princepal9120/aniverse/blob/main/server/internals/middleware/authMiddleware.go"
            TokenUtil["Token Utilities\nserver/internals/utils/tokenUtil.go"]:::backend
            click TokenUtil "https://github.com/princepal9120/aniverse/blob/main/server/internals/utils/tokenUtil.go"
        end
    
        subgraph "Controllers"
            MovieCtrl["Movie Controller\nserver/internals/controllers/movieController.go"]:::backend
            click MovieCtrl "https://github.com/princepal9120/aniverse/blob/main/server/internals/controllers/movieController.go"
            UserCtrl["User Controller\nserver/internals/controllers/userController.go"]:::backend
            click UserCtrl "https://github.com/princepal9120/aniverse/blob/main/server/internals/controllers/userController.go"
        end
    
        AIService["AI Service (LangChain Go)"]:::backend
    end
    
    subgraph "Data Layer"
        DBConn["MongoDB\nserver/internals/database/databaseConnection.go"]:::db
        click DBConn "https://github.com/princepal9120/aniverse/blob/main/server/internals/database/databaseConnection.go"
        MongoDBService(["MongoDB Database"]):::db
    end
    
    subgraph "Seed Initialization"
        Seed["Seed Script\nserver/internals/seed/seed.go"]:::backend
        click Seed "https://github.com/princepal9120/aniverse/blob/main/server/internals/seed/seed.go"
        SeedData["Seed Data Files\nserver/internals/seed/"]:::backend
        click SeedData "https://github.com/princepal9120/aniverse/tree/main/server/internals/seed/"
    end
    
    subgraph "Deployment"
        DockerCompose["Docker Compose\nserver/docker-compose.yml"]:::infra
        click DockerCompose "https://github.com/princepal9120/aniverse/blob/main/server/docker-compose.yml"
        DockerProd["Dockerfile\nserver/dockerfile"]:::infra
        click DockerProd "https://github.com/princepal9120/aniverse/tree/main/server/dockerfile"
        DockerDev["Dockerfile.dev\nserver/dockerfile.dev"]:::infra
        click DockerDev "https://github.com/princepal9120/aniverse/blob/main/server/dockerfile.dev"
        AirConfig["Live Reload Config\nserver/.air.toml"]:::infra
        click AirConfig "https://github.com/princepal9120/aniverse/blob/main/server/.air.toml"
    end

    Browser -->|"Interacts with"| ReactSPA
    ReactSPA -->|"Renders UI + State"| Components
    ReactSPA --> Pages
    ReactSPA --> ProtectedRoute
    ReactSPA --> AuthContext
    ReactSPA --> FavoriteContext
    Components --> APIClient
    Pages --> APIClient
    APIClient -->|"HTTP/JSON"| APIGateway

    APIGateway --> Unprotected
    APIGateway --> Protected
    Protected --> AuthMW
    AuthMW --> TokenUtil
    Unprotected --> UserCtrl
    Protected --> MovieCtrl
    MovieCtrl --> AIService
    UserCtrl --> DBConn
    AIService -->|"Invokes OpenAI"| OpenAI
    AIService --> DBConn

    OpenAI(["OpenAI API"]):::external
    DBConn --> MongoDBService
    Seed --> SeedData
    Seed --> DBConn

    DockerCompose --> APIGateway
    DockerCompose --> MongoDBService

    classDef frontend fill:#E0F7FA,stroke:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20
    classDef db fill:#FFF3E0,stroke:#E65100,stroke-dasharray:5 5
    classDef external fill:#F3E5F5,stroke:#6A1B9A,stroke-dasharray:2 2
    classDef infra fill:#ECEFF1,stroke:#37474F,stroke-dasharray:4 4
```
