# k-forghani/mysterious-family architecture

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

- Interactive diagram: https://gitdiagram.com/k-forghani/mysterious-family
- Repository: https://github.com/k-forghani/mysterious-family

## Overview

##### Project type and purpose
- From the file tree and README we see a C++-based web application (“Mysterious Family”) that implements a secure family-tree data structure.
- It uses the Crow C++ microframework to serve HTML templates and static assets, JSONCpp for JSON handling, plus custom libraries for DAG, secure family-tree (SFT), SHA-256 hashing, and a trie.
- It has two main modes: run the web application (app.cpp) or run tests (test.cpp).

##### File structure
- Top-level files:
- app.cpp – main HTTP server & controller logic
- test.cpp – test harness
- run.sh / clean.sh – build/run scripts
- Dockerfile / .dockerignore – containerization (optional)
- data/ – sample data and a Python generator (data/generate.py)
- libs/ – core data-structure libraries (dag, sft, sha256, trie)
- static/ – CSS & JS assets for client-side visualization (uses cytoscape-dagre, toastify, etc.)
- templates/ – HTML templates (index, explore, view)
- schema/ – UML and project description (not runtime)

##### README for insights
- Dependencies: Crow, JSONCpp, Boost, g++
- Run modes: `./run.sh app` (launch server), `./run.sh test` (self-tests)
- Architecture hint: the UML (`schema/uml.md`) sketches classes for nodes, trees, hashing

##### Main components & their interactions
a. Frontend (Browser)
- HTML templates (templates/*.html)
- Static CSS/JS (static/assets)
- Renders family-tree graphs, CSS styling, client-side controls
b. Web Server (app.cpp using Crow)
- HTTP routing (REST endpoints for index, explore, view)
- Controller layer: parses requests, invokes business logic
c. Business Logic / Model (libs/)
- dag: generic directed-acyclic-graph functions
- sft: secure family-tree operations (add member, query relationships)
- trie: optional indexing (e.g., name lookup)
- sha256: hashing for data integrity/security
d. Data Layer
- data/*.json (or in-memory structures built at startup)
- generate.py: offline data generation for demos/testing
e. External Dependencies
- Crow (HTTP framework)
- JSONCpp (JSON parsing/serialization)
- Boost (utilities)

##### Architectural patterns & design principles
- MVC-like separation: templates/views ↔ controller (app.cpp) ↔ model (libs)
- Single monolithic service (no microservices)
- In-process data storage (no external DB server)
- Test mode demonstrates CLI-based test harness

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Browser["Browser"]:::frontend
        Templates_Index["index.html"]:::frontend
        Templates_Explore["explore.html"]:::frontend
        Templates_View["view.html"]:::frontend
        Static_CSS_Index["index.css"]:::frontend
        Static_CSS_Explore["explore.css"]:::frontend
        JS_Cyto["cytoscape-dagre.js"]:::frontend
        JS_Dagre["dagre.js"]:::frontend
        JS_Toast["toastify-js.js"]:::frontend
    end

    %% Server & Business Logic inside Docker
    subgraph "Docker Container" 
        style Docker_Container stroke-dasharray: 5 5
        direction TB

        %% Web Server
        subgraph "Web Server"
            direction TB
            Router["Crow HTTP Router<br/>(app.cpp)"]:::backend
            ExternalLibs["JSONCpp, Boost"]:::ext
        end

        %% Business Logic
        subgraph "Business Logic (libs/)"
            direction TB
            DAG_h["dag.h"]:::logic
            DAG_cpp["dag.cpp"]:::logic
            SFT_h["sft.h"]:::logic
            SFT_cpp["sft.cpp"]:::logic
            SHA_h["sha256.h"]:::logic
            SHA_cpp["sha256.cpp"]:::logic
            Trie_h["trie.h"]:::logic
            Trie_cpp["trie.cpp"]:::logic
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            JSON_Files[".json files<br/>(data/*.json)"]:::data
            Data_Gen["generate.py"]:::data
        end

        %% Test Harness
        TestHarness["test.cpp"]:::backend

        %% Tooling & Docs
        subgraph "Tooling & Docs"
            direction TB
            RunSH["run.sh"]:::backend
            CleanSH["clean.sh"]:::backend
            Dockerfile["Dockerfile"]:::backend
            DockerIgnore[".dockerignore"]:::backend
            README_MD["README.md"]:::backend
            UML_MD["uml.md"]:::backend
            Desc_PDF["description.pdf"]:::backend
        end
    end

    %% Connections
    Browser -->|"HTTP GET/POST"| Router
    Templates_Index --> Browser
    Templates_Explore --> Browser
    Templates_View --> Browser
    Static_CSS_Index --> Browser
    Static_CSS_Explore --> Browser
    JS_Cyto --> Browser
    JS_Dagre --> Browser
    JS_Toast --> Browser

    Router -->|"invokes APIs"| DAG_h
    Router --> DAG_cpp
    Router --> SFT_h
    Router --> SFT_cpp
    Router --> SHA_h
    Router --> SHA_cpp
    Router --> Trie_h
    Router --> Trie_cpp
    ExternalLibs --> Router

    DAG_h --> JSON_Files
    DAG_cpp --> JSON_Files
    SFT_h --> JSON_Files
    SFT_cpp --> JSON_Files
    SHA_h --> JSON_Files
    SHA_cpp --> JSON_Files
    Trie_h --> JSON_Files
    Trie_cpp --> JSON_Files
    Data_Gen --> JSON_Files

    TestHarness --> DAG_h
    TestHarness --> SFT_h
    TestHarness --> SHA_h
    TestHarness --> Trie_h

    %% Click Events
    click Templates_Index "https://github.com/k-forghani/mysterious-family/blob/main/templates/index.html"
    click Templates_Explore "https://github.com/k-forghani/mysterious-family/blob/main/templates/explore.html"
    click Templates_View "https://github.com/k-forghani/mysterious-family/blob/main/templates/view.html"
    click Static_CSS_Index "https://github.com/k-forghani/mysterious-family/blob/main/static/css/index.css"
    click Static_CSS_Explore "https://github.com/k-forghani/mysterious-family/blob/main/static/css/explore.css"
    click JS_Cyto "https://github.com/k-forghani/mysterious-family/blob/main/static/assets/js/cytoscape-dagre.js"
    click JS_Dagre "https://github.com/k-forghani/mysterious-family/blob/main/static/assets/js/dagre.js"
    click JS_Toast "https://github.com/k-forghani/mysterious-family/blob/main/static/assets/js/toastify-js.js"
    click Router "https://github.com/k-forghani/mysterious-family/blob/main/app.cpp"
    click TestHarness "https://github.com/k-forghani/mysterious-family/blob/main/test.cpp"
    click DAG_h "https://github.com/k-forghani/mysterious-family/blob/main/libs/dag.h"
    click DAG_cpp "https://github.com/k-forghani/mysterious-family/blob/main/libs/dag.cpp"
    click SFT_h "https://github.com/k-forghani/mysterious-family/blob/main/libs/sft.h"
    click SFT_cpp "https://github.com/k-forghani/mysterious-family/blob/main/libs/sft.cpp"
    click SHA_h "https://github.com/k-forghani/mysterious-family/blob/main/libs/sha256.h"
    click SHA_cpp "https://github.com/k-forghani/mysterious-family/blob/main/libs/sha256.cpp"
    click Trie_h "https://github.com/k-forghani/mysterious-family/blob/main/libs/trie.h"
    click Trie_cpp "https://github.com/k-forghani/mysterious-family/blob/main/libs/trie.cpp"
    click JSON_Files "https://github.com/k-forghani/mysterious-family/tree/main/data/"
    click Data_Gen "https://github.com/k-forghani/mysterious-family/blob/main/data/generate.py"
    click RunSH "https://github.com/k-forghani/mysterious-family/blob/main/run.sh"
    click CleanSH "https://github.com/k-forghani/mysterious-family/blob/main/clean.sh"
    click Dockerfile "https://github.com/k-forghani/mysterious-family/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/k-forghani/mysterious-family/blob/main/.dockerignore"
    click README_MD "https://github.com/k-forghani/mysterious-family/blob/main/README.md"
    click UML_MD "https://github.com/k-forghani/mysterious-family/blob/main/schema/uml.md"
    click Desc_PDF "https://github.com/k-forghani/mysterious-family/blob/main/schema/description.pdf"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#bbf,stroke:#333,stroke-width:1px
    classDef logic fill:#bfb,stroke:#333,stroke-width:1px
    classDef data fill:#ffb,stroke:#333,stroke-width:1px
    classDef ext fill:#fdd,stroke:#333,stroke-width:1px
    classDef Docker_Container stroke:#bbb,stroke-dasharray:5 5,fill:none

    class Docker_Container Docker_Container
```
