# solvro/web-planer architecture

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

- Interactive diagram: https://gitdiagram.com/solvro/web-planer
- Repository: https://github.com/solvro/web-planer

## Overview

##### Main Components

A. Frontend Layer (Next.js Application):
- Client-side Components
- Homepage Module
- Plans Module
- Authentication Module
- UI Components Library
- API Routes
- State Management (Atoms)
- Service Layer (USOS Integration)

B. Backend Layer (AdonisJS Application):
- Controllers Layer
- Models Layer
- Middleware Layer
- Database Layer
- USOS Integration Service
- Authentication Service
- Scheduled Tasks (Commands)

C. External Services:
- USOS System
- Database (indicated by migrations)
- Analytics Service (Umami)

##### Component Relationships and Data Flow

**[Client Browser] ←→ [Frontend Next.js App]**
- ↑↓
- [Backend API]
- ↑↓
- ┌─────────┴─────────┐
**[Database] [USOS API] [Analytics]**

##### Detailed Component Breakdown

Frontend (Next.js):
**┌─ Frontend Layer ─────────────────┐**
- Public Pages                  │
- Protected Routes (/plans)     │
- API Routes                    │
- Authentication Flow          │
- USOS Integration Services    │
- ┘

Backend (AdonisJS):
**┌─ Backend Layer ──────────────────┐**
- Auth Controller              │
- Courses Controller           │
- Schedule Controller          │
- Users Controller             │
- Database Models             │
- Middleware Stack            │
- USOS Client                 │
- ┘

##### Technical Stack Indicators

Technology badges or labels:
- Next.js/React for frontend
- AdonisJS for backend
- TypeScript
- Tailwind CSS
- PostgreSQL (implied by migrations)

##### Additional Elements

- Deployment infrastructure (Coolify)
- Environment configurations
- CI/CD workflow connections
- Caching layers if present
- Scheduled tasks and background jobs

Remember to indicate the scalability points and potential bottlenecks in the system, especially around the USOS integration and schedule synchronization features.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]
    end

    subgraph Frontend["Frontend Layer (Next.js)"]
        direction TB
        HomePage["Homepage Module"]:::frontend
        Plans["Plans Module"]:::frontend
        Auth["Authentication Module"]:::frontend
        UI["UI Components"]:::frontend
        APIRoutes["API Routes"]:::frontend
        State["State Management"]:::frontend
        FrontUSOS["USOS Integration"]:::frontend
        AuthRoutes["Auth Routes"]:::frontend
        UserServices["User Services"]:::frontend
    end

    subgraph Backend["Backend Layer (AdonisJS)"]
        direction TB
        Controllers["Controllers Layer"]:::backend
        Models["Models Layer"]:::backend
        Middleware["Middleware Layer"]:::backend
        DBLayer["Database Layer"]:::backend
        BackUSOS["USOS Client"]:::backend
        AuthController["Auth Controller"]:::backend
        Tasks["Scheduled Tasks"]:::backend
        Validators["Validators"]:::backend
    end

    subgraph External["External Services"]
        direction TB
        DB[(PostgreSQL)]:::external
        USOS["USOS System"]:::external
        Analytics["Analytics (Umami)"]:::external
    end

    %% Relationships
    Browser <--> HomePage
    Browser <--> Plans
    Browser <--> Auth

    HomePage --> APIRoutes
    Plans --> APIRoutes
    Auth --> AuthRoutes
    APIRoutes --> Controllers
    AuthRoutes --> AuthController
    
    Controllers <--> Models
    Controllers --> BackUSOS
    Models <--> DBLayer
    DBLayer <--> DB
    
    BackUSOS <--> USOS
    FrontUSOS <--> USOS
    
    Browser --> Analytics

    %% Click Events
    click HomePage "https://github.com/Solvro/web-planer/tree/main/frontend/src/app/(homepage)"
    click Plans "https://github.com/Solvro/web-planer/tree/main/frontend/src/app/plans"
    click Auth "https://github.com/Solvro/web-planer/tree/main/frontend/src/lib/auth"
    click UI "https://github.com/Solvro/web-planer/tree/main/frontend/src/components/ui"
    click APIRoutes "https://github.com/Solvro/web-planer/tree/main/frontend/src/app/api"
    click State "https://github.com/Solvro/web-planer/tree/main/frontend/src/atoms"
    click FrontUSOS "https://github.com/Solvro/web-planer/tree/main/frontend/src/services/usos"
    click Controllers "https://github.com/Solvro/web-planer/tree/main/backend/app/controllers"
    click Models "https://github.com/Solvro/web-planer/tree/main/backend/app/models"
    click Middleware "https://github.com/Solvro/web-planer/tree/main/backend/app/middleware"
    click DBLayer "https://github.com/Solvro/web-planer/tree/main/backend/database"
    click BackUSOS "https://github.com/Solvro/web-planer/blob/main/backend/app/usos/usos_client.ts"
    click AuthController "https://github.com/Solvro/web-planer/blob/main/backend/app/controllers/auth_controller.ts"
    click Tasks "https://github.com/Solvro/web-planer/tree/main/backend/commands"
    click AuthRoutes "https://github.com/Solvro/web-planer/tree/main/frontend/src/app/api/login"
    click UserServices "https://github.com/Solvro/web-planer/blob/main/frontend/src/actions/user.ts"
    click Validators "https://github.com/Solvro/web-planer/tree/main/backend/app/validators"

    %% Styles
    classDef frontend fill:#2563eb,color:white
    classDef backend fill:#16a34a,color:white
    classDef external fill:#6b7280,color:white
    
    %% Legend
    subgraph Legend
        Frontend_L[Frontend Component]:::frontend
        Backend_L[Backend Component]:::backend
        External_L[External Service]:::external
    end
```
