# ssaavedraa/argus architecture

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

- Interactive diagram: https://gitdiagram.com/ssaavedraa/argus
- Repository: https://github.com/ssaavedraa/argus

## Overview

##### Project Type and Purpose
- Argus is a full-stack, Next.js-based dashboard application for real-time data monitoring, advanced visualization, and customizable user layouts.
- The README highlights multi-data monitoring, interactive charts, real-time updates, and seamless integration with external data sources and APIs.

##### File-Structure Analysis
- Top-level config & scripts: `.env.example`, `next.config.mjs`, `tailwind.config.ts`, linting & commit hooks (`.eslintrc.json`, `.husky/`, `commitlint.config.js`).
- “src/app”: Next.js 13 App Router — layouts and pages for `/admin`, `/auth`, root, plus API route under `/api/auth`.
- “src/actions”: Business-logic layer—functions that call databases or external APIs (`getTeams.ts`, `invite.ts`, etc.).
- “src/pages”: Legacy or client-only pages for authentication and signup flows.
- “src/ui”: Design-system components (buttons, cards, modals, tables, etc.).
- “src/utils”: Utility helpers (HTTP fetch wrapper, delay, type-narrowing, validation schemas).
- Other: `public/` for static assets, `package.json` for dependencies (Next.js, React, Tailwind CSS).

##### Insights from README
- Emphasis on Next.js’s SSR/ISR, `next/font` optimization, and a clean commit-message/React component standard.
- No direct database code—data access likely via `hexFetch` to REST/GraphQL services or serverless functions.

a. Client Browser (React/Next.js)
b. Next.js Web Server
- App-Router Pages & Layouts (`src/app`)
- Pages-Router (legacy) (`src/pages`)
- API Routes (`src/app/api/auth/[...nextauth]`)
- Middleware (`src/middleware.ts`) & Auth config (`src/auth.ts`)
c. Business Logic Layer (`src/actions`)
d. UI Component Library (`src/ui`)
e. Utility Layer (`src/utils`)
f. External Services
- Authentication service (NextAuth provider, OAuth or JWT)
- Data Sources / APIs (databases, analytics endpoints)
g. Static Assets (`public/`, global CSS, Tailwind config)

##### Relationships & Data Flow
- User → Browser ←→ Next.js (SSR/CSR)
- Browser → Next.js API route → NextAuth → Auth provider → Browser (login flow)
- Browser → Dashboard page → calls client-side hooks → business logic (`hexFetch`) → external APIs/DB → returns JSON → UI components render charts/tables
- Next.js SSR fetches initial data on the server via `src/actions/*` before rendering.
- Utility functions (validation, delay) augment both client-side forms and server-side handlers.

##### Architectural Patterns & Principles
- Layered architecture (UI ↔ Business Logic ↔ Data).
- Feature-based module separation (`actions/company`, `actions/invite`, `ui/card`, `utils/validation-schemas`).
- Component-based UI (reusable React components under `src/ui`).
- Next.js App Router for nested layouts & route-based code splitting.
- Middleware & API routes for authentication and server-side concerns.

##### Essential Elements
- Clear component labels (folder + filename + purpose).
- Callouts for key Next.js features: SSR, API routes, middleware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level
    Browser["Client Browser<br/>(React/Next.js)"]:::ui -->|HTTP/SSR/CSR| NextJS["Next.js Web Server"]:::logic
    NextJS --> Middleware["Middleware<br/>(src/middleware.ts)"]:::api
    NextJS --> AuthConfig["Auth Config<br/>(src/auth.ts)"]:::api

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        AppRouter["App Router<br/>(src/app)"]:::ui
        PagesRouter["Legacy Pages Router<br/>(src/pages)"]:::ui
        subgraph "Admin Dashboard"
            direction TB
            AdminLayout["Dashboard Layout<br/>(layout.tsx)"]:::ui
            AdminPage["Dashboard Page<br/>(page.tsx)"]:::ui
        end
        TeamsPage["Teams Sub-page<br/>([team]/page.tsx)"]:::ui
        InvitePage["Invite Page<br/>(invite/page.tsx)"]:::ui
        subgraph "Auth Pages"
            direction TB
            AuthLayout["Auth Layout<br/>(layout.tsx)"]:::ui
            LoginPage["Login Page<br/>(login/page.tsx)"]:::ui
            SignupPage["Signup Page<br/>(signup/page.tsx)"]:::ui
        end
    end

    %% API Routes
    subgraph "API Layer"
        direction TB
        NextAuthRoute["NextAuth API Route<br/>([...nextauth]/route.ts)"]:::api
    end

    %% Business Logic
    subgraph "Business Logic Layer<br/>(src/actions)" 
        direction TB
        GetRoles["getRoles<br/>(company/getRoles.ts)"]:::logic
        GetTeams["getTeams<br/>(teams/getTeams.ts)"]:::logic
        GetMembers["getTeamMembers<br/>(teams/getTeamMembers.ts)"]:::logic
        InviteFlow["Invitation Flows<br/>(invite/*.ts)"]:::logic
        GetUser["getUser<br/>(user/getUser.ts)"]:::logic
        LoginAction["login<br/>(login.ts)"]:::logic
    end

    %% UI Component Library
    subgraph "UI Component Library<br/>(src/ui)"
        direction TB
        Button["Button Component<br/>(button/Button.tsx)"]:::ui
        Card["Card Components<br/>(card/*.tsx)"]:::ui
        Modal["Modal Components<br/>(modal/*.tsx)"]:::ui
        Table["Table Components<br/>(table/*.tsx)"]:::ui
    end

    %% Utility Layer
    subgraph "Utility Layer<br/>(src/utils)"
        direction TB
        HexFetch["hexFetch<br/>(hexFetch/hexFetch.ts)"]:::logic
        Delay["delay<br/>(delay/delay.ts)"]:::logic
        TypeNarrow["isValidElementOfType<br/>(type-narrowing)"]:::logic
        Validation["Validation Schemas<br/>(validation-schemas/*.ts)"]:::logic
    end

    %% External Services
    subgraph "External Services & Data"
        direction TB
        AuthProvider["Auth Provider<br/>(OAuth/JWT)"]:::ext
        DataAPI["External APIs/DB"]:::ext
    end

    %% Flows
    Browser -->|visits pages| AppRouter
    Browser --> PagesRouter
    Browser -->|calls| NextAuthRoute
    NextAuthRoute --> AuthProvider
    AuthProvider -->|token| NextAuthRoute
    NextAuthRoute -->|response| Browser

    AppRouter --> AdminLayout
    AdminLayout --> AdminPage
    AdminPage --> TeamsPage
    AdminPage --> InvitePage

    PagesRouter --> LoginPage
    PagesRouter --> SignupPage

    AppRouter --> AuthLayout
    AuthLayout --> LoginPage
    AuthLayout --> SignupPage

    %% Data Fetch Flow
    AdminPage -->|calls| HexFetch
    HexFetch --> GetTeams
    GetTeams --> DataAPI
    DataAPI --> GetTeams
    GetTeams --> AdminPage

    TeamsPage -->|calls| GetMembers
    GetMembers --> DataAPI
    DataAPI --> TeamsPage

    InvitePage -->|calls| InviteFlow
    InviteFlow --> DataAPI
    DataAPI --> InvitePage

    LoginPage -->|calls| LoginAction
    LoginAction --> AuthProvider
    AuthProvider --> LoginAction
    LoginAction -->|user data| LoginPage

    %% UI Components usage
    AdminPage --> Button
    AdminPage --> Card
    AdminPage --> Table
    InvitePage --> Modal

    %% Utils everywhere
    LoginAction --> Validation
    InviteFlow --> Validation
    GetUser --> HexFetch
    GetUser --> DataAPI

    %% Styling & Static Assets
    Browser -->|loads| GlobalsCSS["globals.css"]:::ui
    Browser -->|loads| TailwindConfig["tailwind.config.ts"]:::ui
    Browser -->|loads| PublicAssets["public/"]:::ui

    %% Click Events
    click AppRouter "https://github.com/ssaavedraa/argus/tree/main/src/app"
    click PagesRouter "https://github.com/ssaavedraa/argus/tree/main/src/pages"
    click AdminLayout "https://github.com/ssaavedraa/argus/blob/main/src/app/admin/dashboard/layout.tsx"
    click AdminPage "https://github.com/ssaavedraa/argus/blob/main/src/app/admin/dashboard/page.tsx"
    click TeamsPage "https://github.com/ssaavedraa/argus/blob/main/src/app/admin/dashboard/teams/[team]/page.tsx"
    click InvitePage "https://github.com/ssaavedraa/argus/blob/main/src/app/admin/invite/page.tsx"
    click AuthLayout "https://github.com/ssaavedraa/argus/blob/main/src/app/auth/layout.tsx"
    click LoginPage "https://github.com/ssaavedraa/argus/blob/main/src/app/auth/login/page.tsx"
    click SignupPage "https://github.com/ssaavedraa/argus/blob/main/src/app/auth/signup/page.tsx"
    click NextAuthRoute "https://github.com/ssaavedraa/argus/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click Middleware "https://github.com/ssaavedraa/argus/blob/main/src/middleware.ts"
    click AuthConfig "https://github.com/ssaavedraa/argus/blob/main/src/auth.ts"
    click GetRoles "https://github.com/ssaavedraa/argus/blob/main/src/actions/company/getRoles.ts"
    click GetTeams "https://github.com/ssaavedraa/argus/blob/main/src/actions/teams/getTeams.ts"
    click GetMembers "https://github.com/ssaavedraa/argus/blob/main/src/actions/teams/getTeamMembers.ts"
    click InviteFlow "https://github.com/ssaavedraa/argus/blob/main/src/actions/invite/invite.ts"
    click GetUser "https://github.com/ssaavedraa/argus/blob/main/src/actions/user/getUser.ts"
    click LoginAction "https://github.com/ssaavedraa/argus/blob/main/src/actions/login.ts"
    click Button "https://github.com/ssaavedraa/argus/blob/main/src/ui/button/Button.tsx"
    click Card "https://github.com/ssaavedraa/argus/blob/main/src/ui/card/Card.tsx"
    click Modal "https://github.com/ssaavedraa/argus/blob/main/src/ui/modal/Modal.tsx"
    click Table "https://github.com/ssaavedraa/argus/blob/main/src/ui/table/Table.tsx"
    click HexFetch "https://github.com/ssaavedraa/argus/blob/main/src/utils/hexFetch/hexFetch.ts"
    click Delay "https://github.com/ssaavedraa/argus/blob/main/src/utils/delay/delay.ts"
    click TypeNarrow "https://github.com/ssaavedraa/argus/blob/main/src/utils/type-narrowing/isValidElementOfType.ts"
    click Validation "https://github.com/ssaavedraa/argus/tree/main/src/utils/validation-schemas"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#036;stroke-width:1px
    classDef logic fill:#E8F5E9,stroke:#256;stroke-width:1px
    classDef api fill:#FFF3E0,stroke:#853;stroke-width:1px
    classDef ext fill:#FFEBEE,stroke:#a00;stroke-width:1px
```
