# nayzflux/avermate architecture

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

- Interactive diagram: https://gitdiagram.com/nayzflux/avermate
- Repository: https://github.com/nayzflux/avermate

## Overview

##### High-Level Architecture Overview

The system follows a modern full-stack architecture with these main components:

a) Frontend Layer (Next.js Application):
- Sub-components:
- Authentication Module
- Dashboard Module
- Grade Management
- Profile Management
- Landing Pages
- Settings Management

b) Backend Layer (Hono API):
- Sub-components:
- Auth Routes
- Grade Routes
- Subject Routes
- Period Routes
- User Routes
- Average Calculation Service

c) Database Layer:
- With Drizzle ORM layer

##### Component Relationships

- Client → API (REST calls)
- API → Database (via Drizzle ORM)
- Auth Flow (including social authentication)
- File Upload Flow (for avatars/images)

##### Key Technical Elements

Specific components:
**Frontend:**
- React Query for state management
- shadcn/ui + magic ui for UI components
- TailwindCSS for styling
- Custom hooks layer
- Type definitions layer

**Backend:**
- Rate limiting middleware
- Session management
- Email service (Resend)
- Upload handling (UploadThing)

##### Specific Implementation Details

a) Authentication Flow:
- Social auth providers
- Email verification
- Password reset flow

b) Grade Management Flow:
- Grade calculation pipeline
- Period management
- Subject organization

c) Data Flow:
- How data moves from user input to storage
- Average calculation process
- Data aggregation for dashboard

##### Important Notes

- Microservices-like structure with apps/api and apps/client
- Clear separation between frontend routes and API endpoints
- Real-time calculation features
- Planned integration points for future ED (external data) sync

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Application (Next.js)"]
        direction TB
        Auth["Authentication Module"]:::frontend
        Dashboard["Dashboard Module"]:::frontend
        GradeMgmt["Grade Management"]:::frontend
        Profile["Profile Management"]:::frontend
        Landing["Landing Pages"]:::frontend
        Settings["Settings Management"]:::frontend
        
        ReactQuery["React Query"]:::frontend
        UI["shadcn/ui + magic ui"]:::frontend
        TailwindCSS["TailwindCSS"]:::frontend
        CustomHooks["Custom Hooks"]:::frontend
        Types["Type Definitions"]:::frontend
    end

    subgraph API["API Server (Hono)"]
        direction TB
        AuthRoutes["Auth Routes"]:::backend
        GradeRoutes["Grade Routes"]:::backend
        SubjectRoutes["Subject Routes"]:::backend
        PeriodRoutes["Period Routes"]:::backend
        UserRoutes["User Routes"]:::backend
        AvgCalc["Average Calculation Service"]:::backend
        
        RateLimit["Rate Limiting"]:::middleware
        SessionMgmt["Session Management"]:::middleware
        EmailSvc["Email Service (Resend)"]:::external
        UploadSvc["Upload Handling (UploadThing)"]:::external
    end

    subgraph DB["Database Layer"]
        direction TB
        Turso[(Turso DB)]:::database
        DrizzleORM["Drizzle ORM"]:::database
    end

    %% Connections
    Client --> API
    API --> DB
    DrizzleORM --> Turso

    %% Component Mappings
    click Auth "https://github.com/nayzflux/avermate/tree/main/apps/client/src/app/auth/"
    click Dashboard "https://github.com/nayzflux/avermate/tree/main/apps/client/src/app/dashboard/"
    click GradeMgmt "https://github.com/nayzflux/avermate/tree/main/apps/client/src/app/dashboard/grades/"
    click Profile "https://github.com/nayzflux/avermate/tree/main/apps/client/src/app/profile/"
    click Landing "https://github.com/nayzflux/avermate/tree/main/apps/client/src/app/(landing)/"
    click AuthRoutes "https://github.com/nayzflux/avermate/blob/main/apps/api/src/routes/auth.ts"
    click GradeRoutes "https://github.com/nayzflux/avermate/blob/main/apps/api/src/routes/grades.ts"
    click SubjectRoutes "https://github.com/nayzflux/avermate/blob/main/apps/api/src/routes/subjects.ts"
    click PeriodRoutes "https://github.com/nayzflux/avermate/blob/main/apps/api/src/routes/periods.ts"
    click UserRoutes "https://github.com/nayzflux/avermate/blob/main/apps/api/src/routes/users.ts"
    click DrizzleORM "https://github.com/nayzflux/avermate/tree/main/apps/api/src/db/"
    click EmailSvc "https://github.com/nayzflux/avermate/blob/main/apps/api/src/lib/resend.ts"
    click UploadSvc "https://github.com/nayzflux/avermate/blob/main/apps/api/src/lib/uploadthing.ts"
    click RateLimit "https://github.com/nayzflux/avermate/blob/main/apps/api/src/middlewares/ratelimit.ts"
    click SessionMgmt "https://github.com/nayzflux/avermate/blob/main/apps/api/src/middlewares/session.ts"

    %% Styling
    classDef frontend fill:#2563eb,color:white
    classDef backend fill:#16a34a,color:white
    classDef database fill:#ca8a04,color:white
    classDef external fill:#9333ea,color:white
    classDef middleware fill:#4b5563,color:white

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        Backend["Backend Service"]:::backend
        Database["Database Component"]:::database
        External["External Service"]:::external
        Middleware["Middleware"]:::middleware
    end
```
