# hoanjen/coinflip architecture

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

- Interactive diagram: https://gitdiagram.com/hoanjen/coinflip
- Repository: https://github.com/hoanjen/coinflip

## Overview

##### Main Components
- Frontend: A React.js interface that allows users to place bets and view results.
- Backend: A Node.js/Express API, containing controllers, routes, services, middleware, and models managing business logic, authentication, betting transactions, and database interactions.
- Smart Contract: Written in Solidity, this module (with Hardhat configuration, scripts, and tests) manages on-chain betting, randomness, and result validation.
- External Services/Infrastructure:
- The blockchain network (e.g., Ethereum or an EVM-compatible chain) where the smart contract is deployed.
- MongoDB as a database for storing user data, betting history, and transaction logs.
- Possibly an external blockchain node (like Ganache during development or a live RPC URL).

##### Analyzing the File Structure
- Backend:
- Organized in clear folders like controllers (handling requests), routes (defining API endpoints), services (business logic), models (data schema and plugins), middleware (authentication, error-handling, validation), and utilities.
- Configuration files (config.ts, database.ts, logger.ts, morgan.ts) indicate that logging, database connectivity, and middleware setup are key components.
- SmartContract:
- Contains Solidity contracts, Hardhat’s configuration (hardhat.config.ts), deployment scripts (deploy.ts, verify.ts), and test scripts ensuring correctness.
- Frontend:
- Although details aren’t fully listed, based on the README and naming conventions, it likely uses React components, API service integration, and state management for immediate display and user interaction.

- Backend as the central business logic layer with:
- Controllers and routes receiving incoming requests.
- Services processing the logic (including authentication and betting transactions) and interacting with the database.
- Middleware handling error processing and validation.
- Smart Contract as an independent yet connected component; the backend interacts with the blockchain by making transactions that call the deployed smart contract methods.
- An “External Blockchain Network” component (or similar) to denote the environment where the Smart Contract is deployed.
- A configuration or logging service indicator representing how logs (all.log/error.log) are managed.

##### Key Architectural Patterns & Technologies to Emphasize
- Separation of Concerns: Clearly segregate the concerns of user interface (Frontend), business logic & data management (Backend), and on-chain processing (Smart Contract).
- Use of API layering: The Backend acts as the mediator between the Frontend and Smart Contract.
- Modular design in the Backend where every layer (controllers, services, models) is separated for maintainability and scalability.
- Deployment and testing of Smart Contracts using Hardhat.
- Technologies include Node.js/Express, MongoDB, React.js, Solidity, Hardhat, and possibly blockchain nodes like Ganache.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    F["Frontend (React.js UI)"]:::frontend

    %% Backend API Layer
    subgraph "Backend API"
        B1["Main Application"]:::backend
        B2["Controllers & Routes"]:::backend
        B3["Services"]:::backend
        B4["Middleware"]:::backend
        B5["Database Models"]:::backend
        B6["Configuration & Logging"]:::backend
        B7["Logs"]:::backend
    end

    %% Database Layer
    DB["MongoDB Database"]:::database

    %% Blockchain Interaction Layer
    subgraph "Blockchain Interaction"
        SC["Smart Contract Module"]:::blockchain
        DS["Deployment & Verification Scripts"]:::blockchain
        T["Test Scripts"]:::blockchain
        BN["Blockchain Network (Ethereum/EVM)"]:::blockchain
    end

    %% Connections
    F -->|"HTTP_Request"| B1
    B1 -->|"routes"| B2
    B2 -->|"calls"| B3
    B3 -->|"validation"| B4
    B3 -->|"DB_ops"| B5
    B5 -->|"CRUD"| DB
    B1 -->|"config"| B6
    B6 -->|"logs"| B7
    B3 -->|"blockchain_call"| SC
    SC -->|"deploys_to"| BN
    SC -->|"uses"| DS
    SC -->|"tested_by"| T

    %% Click Events
    click F "https://github.com/hoanjen/coinflip/tree/main/Frontend"
    click B1 "https://github.com/hoanjen/coinflip/blob/main/Backend/src/app.ts"
    click B2 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/controller"
    click B2 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/routes"
    click B3 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/services"
    click B4 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/middleware"
    click B5 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/models"
    click B6 "https://github.com/hoanjen/coinflip/tree/main/Backend/src/config"
    click B7 "https://github.com/hoanjen/coinflip/tree/main/Backend/logs"
    click SC "https://github.com/hoanjen/coinflip/tree/main/SmartContract"
    click DS "https://github.com/hoanjen/coinflip/tree/main/SmartContract/scripts"
    click T "https://github.com/hoanjen/coinflip/tree/main/SmartContract/test"

    %% Styles
    classDef frontend fill:#b3e5fc,stroke:#01579b,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef blockchain fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
```
