# hiperhyped/hh_2 architecture

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

- Interactive diagram: https://gitdiagram.com/hiperhyped/hh_2
- Repository: https://github.com/hiperhyped/hh_2

## Overview

##### Project type and purpose
- This is a multi-platform full-stack Flutter application (“hh_2”) targeting mobile (Android, iOS), desktop (Windows, macOS, Linux) and web.
- It uses AWS Amplify for hosting, authentication and possibly data storage, and it also integrates with a custom PHP-based REST API (under the `/api` folder) for data operations.

##### Top-level file structure analysis
- `lib/src` contains the Flutter client code, organized into:
- config (AI, DB, XML, logging)
- models (business objects)
- services (utility functions)
- pages (UI screens/components)
- `amplify/` holds AWS Amplify configuration and backend definitions (e.g., Cognito auth resources).
- `api/` holds PHP scripts providing REST endpoints (`login.php`, `search.php`, `DBService.php` etc.)
- Platform folders: `android/`, `ios/`, `web/`, `linux/`, `macos/`, `windows/` – autogenerated Flutter embedding code.

##### Key README insights
- Relies on Flutter’s standard multi-platform support and AWS Amplify.

##### Main components
a. Client (Flutter App)
– UI Layer: Flutter Widgets in `lib/src/pages`
– Business Logic & Data Layer: `lib/src/services`, `lib/src/config` (DB service, AI service, logging)
– Models: data classes in `lib/src/models`
b. AWS Amplify Backend
– Authentication (Cognito User Pool) from `amplify/backend/auth`
– Other Amplify services (e.g., S3, AppSync) if configured
c. Custom PHP API Server
– REST endpoints in `/api`
– Database access logic (`DBService.php`, `DBUser.php`, etc.)
d. Database
– Underlying RDBMS (MySQL, PostgreSQL) behind PHP scripts
e. External Services
– AI services (third-party or internal via `lib/src/config/ai`)
– AWS S3 for image storage (XML and S3 config under `lib/src/config/xml`)

##### Relationships and data flows
- User actions in the Flutter UI invoke methods in the services layer (e.g., `db_service`, `ai_service`).
- The services layer issues HTTP requests:
- To AWS Amplify (Cognito) for authentication and token management
- To PHP API endpoints for CRUD operations
- PHP API scripts interact with the database and return JSON payloads.
- Flutter parses JSON into Models and updates the UI.
- AI configuration modules may call external AI endpoints (e.g., OpenAI).

##### Architectural patterns and design principles
- Layered architecture in the Flutter client: UI → Services → API/DB → Models
- Separation of concerns:
- Amplify handles auth and cloud infra
- PHP API handles legacy data access and business rules
- Config-driven modules in `lib/src/config` for easy swapping of implementations (e.g., AI engines)

##### Essential elements checklist
- Clear component names (e.g., “Flutter UI”, “Cognito Auth”, “PHP REST API”)
- Arrowheads indicating request and response flows
- Annotations for major protocols and data formats (JSON over HTTPS, AWS SDK)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Flutter Client"
        UI["UI Layer"]:::client
        Services["Services Layer"]:::client
        ConfigAI["AI Config"]:::client
        ConfigDB["DB Config"]:::client
        ConfigLog["Logging Config"]:::client
        ConfigXML["XML/S3 Config"]:::client
        Models["Models"]:::client
    end

    subgraph "AWS Amplify Backend" 
        Auth["Cognito Auth"]:::backend
        ConfigProj["Project Config"]:::backend
    end

    subgraph "PHP API Server"
        Endpoints["REST Endpoints"]:::backend
        DBLogic["DB Logic"]:::backend
        LegacyDB["Legacy DB Handler"]:::backend
    end

    DB["RDS Database"]:::db
    S3["AWS S3 Storage"]:::storage
    AIExt["External AI Services"]:::external

    UI -->|"calls methods"| Services
    Services -->|"Authenticate (AWS SDK)"| Auth
    Services -->|"CRUD over HTTPS/JSON"| Endpoints
    Services -->|"uses AI config"| ConfigAI
    ConfigAI -->|"HTTP/JSON"| AIExt
    Endpoints -->|"includes"| DBLogic
    DBLogic -->|"SQL Queries"| DB
    ConfigXML -->|"XML/S3 over SDK"| S3

    click UI "https://github.com/hiperhyped/hh_2/tree/main/lib/src/pages"
    click Services "https://github.com/hiperhyped/hh_2/tree/main/lib/src/services"
    click ConfigAI "https://github.com/hiperhyped/hh_2/tree/main/lib/src/config/ai"
    click ConfigDB "https://github.com/hiperhyped/hh_2/tree/main/lib/src/config/db"
    click ConfigLog "https://github.com/hiperhyped/hh_2/blob/main/lib/src/config/log/log_service.dart"
    click ConfigXML "https://github.com/hiperhyped/hh_2/blob/main/lib/src/config/xml/xml_s3_data.dart"
    click Models "https://github.com/hiperhyped/hh_2/tree/main/lib/src/models"
    click Auth "https://github.com/hiperhyped/hh_2/tree/main/amplify/backend/auth/hh2cb46d1ef"
    click ConfigProj "https://github.com/hiperhyped/hh_2/blob/main/amplify/.config/project-config.json"
    click Endpoints "https://github.com/hiperhyped/hh_2/blob/main/api/*.php"
    click DBLogic "https://github.com/hiperhyped/hh_2/blob/main/api/DBService.php"
    click DBLogic "https://github.com/hiperhyped/hh_2/blob/main/api/DBUser.php"
    click LegacyDB "https://github.com/hiperhyped/hh_2/blob/main/db_handler.php"

    classDef client fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef backend fill:#FAD7A0,stroke:#B9770E,color:#7E5109;
    classDef db fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef storage fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef external stroke-dasharray:5 5,fill:#F5F5F5,stroke:#7B7D7D,color:#616A6B;
```
