# xxthunderblastxx/neoshare architecture

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

- Interactive diagram: https://gitdiagram.com/xxthunderblastxx/neoshare
- Repository: https://github.com/xxthunderblastxx/neoshare

## Overview

##### Main System Components

a. Frontend Layer:
- Located in `/cmd/web`
- Uses HTMX, HyperScript, and TailwindCSS
- Components include authentication, dashboard, and file management views

b. Backend Layer:
- Core API service in `/cmd/api`
- Multiple internal packages for business logic
- Authentication handling
- File management services

c. External Services:
- S3-compatible storage
- OIDC/Auth0 authentication
- PostgreSQL database

##### Architectural Pattern
The project follows a clean architecture pattern with clear separation of concerns:

- Handlers (HTTP/Web Interface)
- Services (Business Logic)
- Repositories (Data Access)
- Models (Domain Objects)

**[Client Browser] ←→ [Frontend Layer (HTMX/Hyperscript)]**
- ↓
**[Backend API Layer]**
- ↙     ↓     ↘
**[Auth0] [S3]  [PostgreSQL]**

##### Client Layer
- Web Browser
- HTMX/HyperScript interactions
- TailwindCSS/DaisyUI styling

##### Frontend Components
- Authentication views
- Dashboard interface
- File management UI
- Template components

##### Backend Services
- API endpoints
- Authentication middleware
- Rate limiting
- Session management
- File service
- S3 service

##### External Services
- S3 Storage
- Auth0/OIDC Provider
- PostgreSQL Database

- Blue: Frontend components
- Green: Backend services
- Yellow: External services
- Red: Security/Authentication components
- Gray: Database/Storage

Relationships to Highlight:
##### Client-Server Communication
- HTMX requests
- File upload/download flows
- Authentication flows

##### Backend Interactions
- Database queries
- S3 storage operations
- Authentication verification

##### Data Flow
- File upload path
- File download path
- User authentication flow

Special Considerations:
##### Security Layer
- Middleware placement
- Rate limiting
- Token verification

##### Storage Flow
- File upload to S3
- Database metadata storage
- Direct download links

##### Authentication Flow
- OIDC authentication
- Callback handling
- Session management

Level of Detail:
- Keep high-level components visible
- Important middleware
- Primary data flows

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    Client["Client Browser"]:::client

    %% Frontend Layer
    subgraph Frontend
        HTMX["HTMX/HyperScript Interface"]:::frontend
        AuthUI["Authentication UI"]:::frontend
        DashUI["Dashboard UI"]:::frontend
        FileUI["File Management UI"]:::frontend
        Components["UI Components"]:::frontend
        Assets["Static Assets"]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        API["API Core"]:::backend
        
        subgraph Services
            AuthService["Authentication Service"]:::service
            FileService["File Service"]:::service
            S3Service["S3 Service"]:::service
            SessionMgmt["Session Management"]:::service
        end
        
        subgraph Security
            RateLimit["Rate Limiter"]:::security
            TokenVerify["Token Verification"]:::security
            Middleware["General Middleware"]:::security
        end
        
        subgraph Routes
            AuthRoutes["Auth Routes"]:::route
            DashRoutes["Dashboard Routes"]:::route
            MainRoutes["Main Routes"]:::route
        end
        
        subgraph Data
            Models["Data Models"]:::data
            Repository["Repository Layer"]:::data
            Config["Configuration"]:::data
        end
    end

    %% External Services
    subgraph External
        Auth0["Auth0/OIDC"]:::external
        S3["S3 Storage"]:::external
        DB["PostgreSQL"]:::external
    end

    %% Relationships
    Client --> HTMX
    HTMX --> AuthUI & DashUI & FileUI
    AuthUI & DashUI & FileUI --> Components
    Components --> Assets

    HTMX --> API
    API --> Security
    Security --> Routes
    Routes --> Services
    Services --> Repository
    Repository --> DB
    FileService --> S3
    AuthService --> Auth0
    
    %% Click Events
    click AuthUI "https://github.com/XxThunderBlastxX/neoshare/blob/main/cmd/web/page/auth.templ"
    click DashUI "https://github.com/XxThunderBlastxX/neoshare/blob/main/cmd/web/page/dashboard.templ"
    click FileUI "https://github.com/XxThunderBlastxX/neoshare/blob/main/cmd/web/page/files.templ"
    click Components "https://github.com/XxThunderBlastxX/neoshare/tree/main/cmd/web/component/"
    click Assets "https://github.com/XxThunderBlastxX/neoshare/tree/main/cmd/web/assets/"
    click API "https://github.com/XxThunderBlastxX/neoshare/blob/main/cmd/api/main.go"
    click AuthService "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/auth/auth.go"
    click FileService "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/service/file.go"
    click S3Service "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/service/s3.go"
    click SessionMgmt "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/session/session.go"
    click Repository "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/repository/db.go"
    click RateLimit "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/middleware/rate_limiter.go"
    click TokenVerify "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/middleware/verify_token.go"
    click Middleware "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/middleware/middleware.go"
    click AuthRoutes "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/routes/auth_router.go"
    click DashRoutes "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/routes/dashboard_router.go"
    click MainRoutes "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/routes/routes.go"
    click Models "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/model/model.go"
    click Config "https://github.com/XxThunderBlastxX/neoshare/blob/main/internal/config/config.go"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef frontend fill:#9cf,stroke:#333,stroke-width:2px
    classDef backend fill:#9f9,stroke:#333,stroke-width:2px
    classDef service fill:#6f6,stroke:#333,stroke-width:2px
    classDef security fill:#f66,stroke:#333,stroke-width:2px
    classDef route fill:#ff9,stroke:#333,stroke-width:2px
    classDef data fill:#ccc,stroke:#333,stroke-width:2px
    classDef external fill:#fc9,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["Client"]:::client
        L2["Frontend"]:::frontend
        L3["Backend"]:::backend
        L4["Services"]:::service
        L5["Security"]:::security
        L6["Routes"]:::route
        L7["Data"]:::data
        L8["External"]:::external
    end
```
