# arielsltty/ipchain-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/arielsltty/ipchain-tracker
- Repository: https://github.com/arielsltty/ipchain-tracker

## Overview

##### Project type and purpose
- This is a full-stack decentralized application (“dApp”) built on the Internet Computer Protocol (ICP).
- Backend: Smart canister written in Motoko (src/ipblock_backend/main.mo).
- Frontend: React + Tailwind CSS (src/ipblock_frontend).
- Purpose: Track user login IPs, provide audit history, anomaly detection, and map visualization, all on‐chain.

##### File structure
- Top level: dfx.json (ICP canister config), package.json, tsconfig.json.
- src/declarations: auto‐generated TypeScript bindings for backend and frontend canisters.
- src/ipblock_backend: Motoko smart canister.
- src/ipblock_frontend: React app with Vite config, components, public assets, styles.

##### Key points from README
- Uses Internet Identity (WebAuthn) for login.
- Data stored immutably on blockchain via smart canister.
- Real-time anomaly detection and geo‐location map.

##### Main components
a. User’s Browser (React SPA)
b. Internet Identity Service (WebAuthn auth provider)
c. ICP Network & Smart Canister (Motoko backend)
d. Persistent Blockchain Storage (ICP ledger within the canister)
e. GeoIP Service or Internal GeoIP Module
f. Anomaly Detection Logic (inside canister)
g. External Map Library (in React)
h. dfx Management Interface (optional, for deployment)

##### Relationships & data flow
1. User → Browser SPA: HTTP(s) serving index.html & React assets via Vite dev server or CDN.
2. Browser → Internet Identity: WebAuthn handshake for login.
3. Browser → Canister: authenticated ic.invoke calls (e.g., recordLogin(ip, deviceInfo)).
4. Canister → Internal GeoIP: resolve IP→location (or call external GeoIP API).
5. Canister stores login record + geolocation + timestamp on‐chain.
6. Canister triggers anomaly detection logic: compares new login vs historical records.
7. On fetch requests, Canister returns audit trail & anomaly flags.
8. Browser → Map Component: consumes canister data to render world map visualization.

##### Architectural patterns & tech
- Decentralized backend: single canister encapsulating state, business logic, storage.
- Client‐canister RPC via Internet Identity principals.
- React SPA as thin client, uses Vite and Tailwind.
- MVC‐style separation: React components (View), canister methods (Controller/Model).
- dfx.json defines canister build/deploy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        SPA["React SPA"]:::frontend
        Vite["Vite Dev Server / CDN"]:::frontend
        Main["main.jsx"]:::frontend
        Landing["LandingPage.jsx"]:::frontend
        Header["Header.jsx"]:::frontend
        Theme["ThemeToggle.jsx"]:::frontend
        Audit["Audit.jsx"]:::frontend
        History["History.jsx"]:::frontend
        Map["GeoIPMap.jsx"]:::frontend
        Styles["index.scss"]:::frontend
        Assets[".ic-assets.json5"]:::frontend
    end

    subgraph "Auth Layer"
        IIdentity["Internet Identity Service"]:::external
    end

    subgraph "Backend Layer"
        Canister["Motoko Smart Canister"]:::blockchain
        GeoModule["GeoIP Resolver Module"]:::blockchain
        Anomaly["Anomaly Detection Logic"]:::blockchain
        Storage["On-chain Storage"]:::blockchain
    end

    subgraph "Canister Config & Declarations"
        dfxNode["dfx.json"]:::infra
        DeclsBackend["Backend Declarations"]:::infra
        DeclsFrontend["Frontend Declarations"]:::infra
    end

    subgraph "Package & TS Config"
        PkgRoot["package.json & lock"]:::infra
        PkgFront["Frontend package.json"]:::infra
        TSRoot["tsconfig.json"]:::infra
        TSFront["tsconfig.json (frontend)"]:::infra
    end

    Vite -->|"serves assets"| SPA
    SPA -->|"authenticate"| IIdentity
    SPA -->|"recordLogin(ip, deviceInfo)"| Canister
    Canister -->|"lookupGeoIP(ip)"| GeoModule
    Canister -->|"store record"| Storage
    Canister -->|"run anomaly detection"| Anomaly
    SPA -->|"getAuditTrail() / getHistory()"| Canister
    SPA -->|"render map"| Map
    dfxNode -->|"deploy/build"| Canister
    DeclsBackend -->|"used by"| SPA
    DeclsFrontend -->|"used by"| SPA

    classDef frontend fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef external fill:#FFD580,stroke:#FFA500,color:#000
    classDef blockchain fill:#90EE90,stroke:#008000,color:#000
    classDef infra fill:#D3D3D3,stroke:#808080,color:#000

    click SPA "https://github.com/arielsltty/ipchain-tracker/tree/main/src/ipblock_frontend/"
    click Vite "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/index.html"
    click Vite "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/vite.config.js"
    click Main "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/main.jsx"
    click Landing "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/LandingPage.jsx"
    click Header "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/Header.jsx"
    click Theme "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/ThemeToggle.jsx"
    click Audit "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/Audit.jsx"
    click History "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/History.jsx"
    click Map "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/GeoIPMap.jsx"
    click Styles "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/src/index.scss"
    click Assets "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/public/.ic-assets.json5"
    click Canister "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_backend/main.mo"
    click dfxNode "https://github.com/arielsltty/ipchain-tracker/blob/main/dfx.json"
    click DeclsBackend "https://github.com/arielsltty/ipchain-tracker/tree/main/src/declarations/ipblock_backend/"
    click DeclsFrontend "https://github.com/arielsltty/ipchain-tracker/tree/main/src/declarations/ipblock_frontend/"
    click PkgRoot "https://github.com/arielsltty/ipchain-tracker/blob/main/package.json"
    click PkgFront "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/package.json"
    click TSRoot "https://github.com/arielsltty/ipchain-tracker/blob/main/tsconfig.json"
    click TSFront "https://github.com/arielsltty/ipchain-tracker/blob/main/src/ipblock_frontend/tsconfig.json"
```
