# guiartbp/hackathon-qitech architecture

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

- Interactive diagram: https://gitdiagram.com/guiartbp/hackathon-qitech
- Repository: https://github.com/guiartbp/hackathon-qitech

## Overview

##### Project type and purpose
- This is a full-stack P2P finance platform.
- Frontend: Next.js + Tailwind UI layers under `web/src/app/(frontend)` and React components in `web/src/components`.
- Backend: Next.js API routes under `web/src/app/(backend)/api` plus standalone routes in `web/src/app/api`.
- Data layer: PostgreSQL via Prisma (Supabase).
- External services: Stripe Connect (OAuth, webhooks), Blockchain/EVM (Solidity & Hardhat), BetterAuth, AWS KMS, Python ML engine.

##### File structure
- Root folders:
- `web/` : the monorepo’s Next.js app (UI + serverless functions).
- `bruno/`: Bruno API specification & mocks (used for API contract testing).
- Scripts & config: Prisma migrations in `web/prisma`, Hardhat under `web/contracts` & `web/ignition`, deployment scripts in `web/scripts`, tests in `web/tests`.
- Architectural patterns:
- Hybrid Next.js with separate `(backend)` folder for API logic & `(frontend)` for UI.
- Service layer under `web/src/app/(backend)/services`, schema definitions under `web/src/app/(backend)/schemas`.
- Microservice: Python FastAPI scoring engine runs separately.
- Smart contracts managed by Hardhat + TypeChain, deployed via scripts.
- Config and infra files:
- `.env.example` for env vars, `hardhat.config.ts`, `pnpm-workspace.yaml`, Docker/AWS KMS references in README.

##### README for additional insights
- Describes high-level workflow: user auth (BetterAuth), Stripe data ingestion, ML score, on-chain contract creation, dynamic payments via Stripe, audit via webhooks.
- Stacks: Next.js + Node.js for API, Python + Scikit-learn for ML, Solidity for on-chain, PostgreSQL/Prisma, Stripe Connect + OAuth, BetterAuth, Docker + AWS KMS.

##### Don’t overthink—capture all distinct components
- Static assets & public routes (public folder) as part of FE.
- Test mocks (Bruno) if illustrating CI/integration tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        NextJSFrontend["Next.js Frontend\n(web/src/app/(frontend))"]:::app
        ReactComponents["Shared React Components\n(web/src/components)"]:::app
        PublicAssets["Static Assets & Public Routes"]:::app
    end

    %% Backend Layer
    subgraph "Serverless / Node.js Backend"
        AuthModule["Auth Module\n(web/src/app/(backend)/api/auth)"]:::app
        StripeModule["Stripe Module\n(web/src/app/api/stripe)"]:::app
        ScoreService["Score Service\n(ML Score Requests)"]:::service
        OnChainOrch["On-chain Orchestration\n(Hardhat Manager)"]:::app
        WebhookHandlers["Stripe Webhook Handlers\n(web/src/app/api/stripe/webhook/route.ts)"]:::app
    end

    %% Data Layer
    PrismaLayer["Prisma ORM\n(web/prisma/schema.prisma)"]:::db
    Postgres["PostgreSQL (Supabase)"]:::db

    %% External Services
    BetterAuth["BetterAuth"]:::external
    Stripe["Stripe Connect"]:::external
    ML["Python ML Engine\n(FastAPI)"]:::service
    Blockchain["Blockchain Network\n(EVM)"]:::chain
    AWSKMS["AWS KMS"]:::external
    Bruno["Bruno Mock Server"]:::external

    %% Connections
    Browser["Client Browser"]:::app
    Browser --> NextJSFrontend
    NextJSFrontend --> ReactComponents
    NextJSFrontend --> PublicAssets
    NextJSFrontend --> AuthModule
    NextJSFrontend --> StripeModule
    NextJSFrontend --> ScoreService
    NextJSFrontend --> OnChainOrch

    AuthModule --> BetterAuth
    AuthModule --> PrismaLayer
    StripeModule --> Stripe
    StripeModule --> AWSKMS
    StripeModule --> WebhookHandlers
    WebhookHandlers --> Stripe
    WebhookHandlers --> PrismaLayer

    ScoreService --> ML
    ScoreService --> PrismaLayer

    OnChainOrch --> Blockchain
    OnChainOrch --> AWSKMS

    PrismaLayer --> Postgres

    Bruno --> AuthModule
    Bruno --> StripeModule

    %% Click Events
    click NextJSFrontend "https://github.com/guiartbp/hackathon-qitech/tree/main/web/src/app/(frontend)"
    click ReactComponents "https://github.com/guiartbp/hackathon-qitech/tree/main/web/src/components"
    click AuthModule "https://github.com/guiartbp/hackathon-qitech/blob/main/web/src/app/(backend)/api/auth/[...all]/route.ts"
    click StripeModule "https://github.com/guiartbp/hackathon-qitech/blob/main/web/src/lib/stripe-oauth.ts"
    click WebhookHandlers "https://github.com/guiartbp/hackathon-qitech/blob/main/web/src/app/api/stripe/webhook/route.ts"
    click PrismaLayer "https://github.com/guiartbp/hackathon-qitech/blob/main/web/prisma/schema.prisma"
    click OnChainOrch "https://github.com/guiartbp/hackathon-qitech/blob/main/web/hardhat.config.ts"

    %% Styles
    classDef app fill:#D0E8FF,stroke:#0366d6,color:#000;
    classDef db fill:#C8E6C9,stroke:#256029,color:#000;
    classDef service fill:#E0E0E0,stroke:#424242,color:#000;
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef chain fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
