# oxilonx/aetheric architecture

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

- Interactive diagram: https://gitdiagram.com/oxilonx/aetheric
- Repository: https://github.com/oxilonx/aetheric

## Overview

##### Project Type and Purpose
- This is a full-stack e-commerce style application.
- Frontend: React (Vite) single-page application.
- Backend: Node.js + Express REST API, with user and product management.
- Data store: relational database (configured in backend/config/database.sql) and local file storage (backend/uploads).

##### File-Structure Analysis
- Top Level
- backend/ – Express app, MVC-style controllers, routes, middleware, config, utils, file uploads.
- frontend/ – Vite-powered React app, organized into pages, components (UI, local, utility), contexts, assets.
- Backend Patterns
- controllers/ ↔ routes/ implements REST endpoints (users, products)
- middleware/ for JWT auth (authToken.js) and role checking (isAdmin.js)
- config/ for DB connection (db.js + SQL schema)
- utils/ for token generation and SKU logic
- Frontend Patterns
- src/pages/ – route targets: Home, Cart, Profile, Register
- src/components/ – divided into localComponents (feature widgets), ui (visual primitives), utilityComponents (e.g. SkeletonGrid, token handler)
- src/contexts/ – global state (AuthContextProvider, ProdsContextProvider)
- API calls centralized in utilityComponents or lib/utils.js

1. Web Client (React SPA)
– UI Components, Context Providers
– HTTP(S) client for REST calls, handles JWT in Authorization header
2. API Gateway / Backend (Express)
– Routes → Controllers → Business Logic
– Middleware for authentication & authorization
– Utility modules (tokenHelpers, skuGenerator)
3. Database
– User and Product tables (configured via database.sql)
4. File Storage
– Local filesystem at /uploads/products for product images
5. (Optional) External Services
– Email/SMS providers, payment gateways, etc.

b. Relationships & Data Flows
- Browser →(HTTP REST: GET/POST/PUT/DELETE)→ API
- API →(SQL queries)→ Database
- API →(read/write)→ File Storage
- Authentication
- Login/Register: SPA → POST /users → API → tokenHelpers → returns JWT
- Protected calls: React reads JWT from context → sends in Authorization header → authToken middleware validates
- Admin flows: isAdmin middleware grants access to product-management endpoints

c. Architectural Patterns & Principles
- Backend: MVC-style separation (routes/controllers/utils)
- Frontend: Component-based UI + Context API for state management
- Token-based stateless authentication (JWT)
- Single source of truth for API base URL and token handling in utility modules

d. Key Technologies
- Frontend: React, Vite, Context API, JSX, CSS modules (index.css)
- Backend: Node.js, Express, MySQL/PostgreSQL (via db.js), JWT
- Build & lint: ESLint (frontend), Vite config, package.json scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser("Web Browser"):::external

    subgraph "Frontend (React SPA)"
        direction TB
        Main["main.jsx"]:::frontend
        App["App.jsx"]:::frontend
        Layout["Layout.jsx"]:::frontend
        subgraph "Contexts"
            AuthCtx["AuthContextProvider.jsx"]:::frontend
            ProdsCtx["ProdsContextProvider.jsx"]:::frontend
        end
        subgraph "Pages"
            Home["Home.jsx"]:::frontend
            Cart["Cart.jsx"]:::frontend
            Profile["Profile.jsx"]:::frontend
            Register["Register.jsx"]:::frontend
        end
        subgraph "Components"
            UIComps["UI Components"]:::frontend
            LocalComps["Local UI Components"]:::frontend
            UtilComps["Utility Components"]:::frontend
            TokenHandler["authorizationTokenHandler.js"]:::frontend
        end
        LibUtils["utils.js"]:::frontend
    end

    subgraph "Backend (Express API)"
        direction TB
        Server["server.js"]:::backend
        subgraph "Routes"
            UsersRoutes["usersRoutes.js"]:::backend
            ProductsRoutes["productsRoutes.js"]:::backend
        end
        subgraph "Controllers"
            UsersController["usersController.js"]:::backend
            ProductsController["productsController.js"]:::backend
        end
        subgraph "Middleware"
            AuthMiddleware["authToken.js"]:::backend
            AdminMiddleware["isAdmin.js"]:::backend
        end
        subgraph "Utilities"
            TokenHelpers["tokenHelpers.js"]:::backend
            SKUGen["skuGenerator.js"]:::backend
        end
        ConfigDB["db.js"]:::backend
        SchemaSQL["database.sql"]:::backend
    end

    Database("Relational Database"):::datastore
    FileStorage("File Storage (/uploads/products)"):::datastore

    Browser -->|HTTP/JSON| Main
    Main --> App
    App --> Layout
    Layout --> AuthCtx
    Layout --> ProdsCtx
    Layout --> Home
    Layout --> Cart
    Layout --> Profile
    Layout --> Register
    App --> UIComps
    App --> LocalComps
    App --> UtilComps
    UtilComps --> TokenHandler
    UtilComps --> LibUtils

    Layout -->|REST API calls| Server
    Server --> UsersRoutes
    Server --> ProductsRoutes
    UsersRoutes --> UsersController
    ProductsRoutes --> ProductsController
    UsersController --> TokenHelpers
    ProductsController --> SKUGen
    Server --> AuthMiddleware
    Server --> AdminMiddleware

    Server -->|SQL queries| ConfigDB
    ConfigDB --> SchemaSQL
    Server -->|SQL queries| Database
    Server -->|read/write files| FileStorage

    classDef frontend fill:#D0E8FF,stroke:#005B9A,color:#000
    classDef backend fill:#E2F8E8,stroke:#107C10,color:#000
    classDef datastore fill:#FFEBCD,stroke:#D2691E,color:#000
    classDef external fill:#F0F0F0,stroke:#888,color:#000

    click Main "https://github.com/oxilonx/aetheric/blob/main/frontend/src/main.jsx"
    click App "https://github.com/oxilonx/aetheric/blob/main/frontend/src/App.jsx"
    click Layout "https://github.com/oxilonx/aetheric/blob/main/frontend/src/Layout.jsx"
    click UIComps "https://github.com/oxilonx/aetheric/tree/main/frontend/src/components/ui"
    click LocalComps "https://github.com/oxilonx/aetheric/tree/main/frontend/src/components/localComponents"
    click UtilComps "https://github.com/oxilonx/aetheric/tree/main/frontend/src/components/utilityComponents"
    click TokenHandler "https://github.com/oxilonx/aetheric/blob/main/frontend/src/components/utilityComponents/authorizationTokenHandler.js"
    click LibUtils "https://github.com/oxilonx/aetheric/blob/main/frontend/src/lib/utils.js"
    click AuthCtx "https://github.com/oxilonx/aetheric/blob/main/frontend/src/contexts/AuthContextProvider.jsx"
    click ProdsCtx "https://github.com/oxilonx/aetheric/blob/main/frontend/src/contexts/ProdsContextProvider.jsx"
    click Home "https://github.com/oxilonx/aetheric/blob/main/frontend/src/pages/Home.jsx"
    click Cart "https://github.com/oxilonx/aetheric/blob/main/frontend/src/pages/Cart.jsx"
    click Profile "https://github.com/oxilonx/aetheric/blob/main/frontend/src/pages/Profile.jsx"
    click Register "https://github.com/oxilonx/aetheric/blob/main/frontend/src/pages/Register.jsx"
    click Server "https://github.com/oxilonx/aetheric/blob/main/backend/server.js"
    click UsersRoutes "https://github.com/oxilonx/aetheric/blob/main/backend/routes/usersRoutes.js"
    click ProductsRoutes "https://github.com/oxilonx/aetheric/blob/main/backend/routes/productsRoutes.js"
    click UsersController "https://github.com/oxilonx/aetheric/blob/main/backend/controllers/usersController.js"
    click ProductsController "https://github.com/oxilonx/aetheric/blob/main/backend/controllers/productsController.js"
    click AuthMiddleware "https://github.com/oxilonx/aetheric/blob/main/backend/middleware/authToken.js"
    click AdminMiddleware "https://github.com/oxilonx/aetheric/blob/main/backend/middleware/isAdmin.js"
    click ConfigDB "https://github.com/oxilonx/aetheric/blob/main/backend/config/db.js"
    click SchemaSQL "https://github.com/oxilonx/aetheric/blob/main/backend/config/database.sql"
    click TokenHelpers "https://github.com/oxilonx/aetheric/blob/main/backend/utils/tokenHelpers.js"
    click SKUGen "https://github.com/oxilonx/aetheric/blob/main/backend/utils/skuGenerator.js"
    click FileStorage "https://github.com/oxilonx/aetheric/tree/main/backend/uploads/products"
```
