# debugger-demons/whoknows architecture

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

- Interactive diagram: https://gitdiagram.com/debugger-demons/whoknows
- Repository: https://github.com/debugger-demons/whoknows

## Overview

##### Project Type and Purpose
- This is a full-stack, two-component web application: a modern Rust-based frontend and a Rust-based backend service, replacing an earlier Python monolith. Its purpose is to serve as a high-performance, secure “WhoKnows” knowledge‐discovery search engine, with a clean HTML/JS UI and an Actix-web API layer backed by SQLx and a relational database.

##### File Structure
- Top level:
- backend/ – Rust backend service (Actix-web, SQLx) with its own docs, Dockerfile, migration scripts, and CI configuration
- frontend/ – Rust-based front end (likely Yew or static-server) plus static HTML/JS assets, Dockerfile
- database/ – raw schema.sql for initial DB bootstrap
- deployment/ & docker-compose.*.yml – orchestration scripts for Dev/Prod and CI/CD pipelines
- docs/ – global docs, including architecture and legacy analyses
- CI/CD: GitHub Actions workflows in .github/workflows drive build, test, CD to dev/prod environments
- Environment: .env templates for local/deployment setups

##### Extract Key Architectural Insights from the README
- Two distinct Rust services communicating over HTTP
- Database layer evolving from SQLite to Postgres, using SQLx for compile-time query safety
- DevOps focus with Docker, Docker Compose, GitHub Actions, and scripted deployments
- Emphasis on async runtime (Tokio), serialization (Serde), and structured logging (env_logger + log)

a. Main Components
- User’s Browser (UI) – static HTML/CSS/JS
- Frontend Service – Rust binary or static‐file server with proxy middleware
- Backend Service – Actix-web API
- Database – PostgreSQL (or SQLite in dev)
- CI/CD Pipeline – GitHub Actions workflows
- Docker/Docker Compose – orchestration layer for local/dev/prod

b. Relationships & Data Flows
- Browser → Frontend Service: HTTP GET/POST requests for pages and SPA API calls
- Frontend Service → Backend Service: proxied REST API calls over HTTP
- Backend Service → Database: SQLx queries over TCP (Postgres)
- CI/CD → Docker Registry / Kubernetes / Servers: pushes images and triggers deployments
- DevOps Scripts → Cloud Environment: secret setup, image pulls, infrastructure provisioning

c. Architectural Patterns & Principles
- Layered Architecture: clear separation of Presentation, API and Data layers
- Microservice-style boundary between frontend and backend (even if co-located)
- Infrastructure as Code: Docker Compose files, deployment scripts, CI workflows
- Compile-time safety: SQLx, Rust’s type system, strict Cargo dependency management

d. Key Technologies & Frameworks
- Rust 1.x with Actix-web 4.x for HTTP server
- SQLx 0.7 for database access
- Tokio 1.0 for async runtime
- Serde 1.0 for serialization
- env_logger/log for observability
- Docker & Docker Compose for containerization
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UserBrowser["User's Browser"]:::frontend
        StaticAssets["Static Assets"]:::frontend
        FrontendService["Rust Frontend Service"]:::frontend
        FrontendMain["src/main.rs"]:::frontend
        FrontendCargo["Cargo.toml"]:::frontend
        FrontendDockerfile["Dockerfile"]:::frontend
        FrontendDocs["architecture.md"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        BackendService["Actix-web API Service"]:::backend
        BackMain["src/main.rs"]:::backend
        BackCargo["Cargo.toml"]:::backend
        BackDockerfile["Dockerfile"]:::backend
        BackMigration["whoknows.tables.sql"]:::database
        BackAPIDocs["api.md"]:::backend
        BackArchDocs["architecture.md"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database["PostgreSQL Database"]:::database
        DBSchema["schema.sql"]:::database
    end

    %% Docker Network
    subgraph "Docker Network"
        direction TB
        UserBrowser --> StaticAssets --> FrontendService
        FrontendService --> BackendService
        BackendService --> Database
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GHValidate["validate.env_and_secrets.yml"]:::devops
        GHVerify["verify-secret-hash.yml"]:::devops
        GHBuild["build.yml"]:::devops
        GHDev["cd.dev.yml"]:::devops
        GHProd["cd.prod.yml"]:::devops
        GHRelease["release.yml"]:::devops

        GHValidate --> GHBuild
        GHVerify --> GHBuild
        GHBuild --> GHDev
        GHBuild --> GHProd
        GHBuild --> GHRelease
    end

    %% Deployment Scripts
    subgraph "Deployment Scripts"
        direction TB
        DeploySh["deploy.sh"]:::devops
        LoginSh["docker-login.sh"]:::devops
        SetupSecrets["setup_gh_secrets.sh"]:::devops

        GHProd --> DeploySh
        DeploySh --> LoginSh
        DeploySh --> SetupSecrets
    end

    %% Environment Templates
    subgraph "Env Config Templates"
        direction TB
        EnvRoot[".env.template"]:::devops
        EnvBackend["backend/.env.local.backend.template"]:::devops
        EnvFrontend["frontend/.env.local.frontend.template"]:::devops
    end

    %% Compose Files
    subgraph "Docker Compose Files"
        direction TB
        DCYML["docker-compose.yml"]:::devops
        DCDev["docker-compose.dev.yml"]:::devops
        DCProd["docker-compose.prod.yml"]:::devops
    end

    %% Global Documentation
    subgraph "Global Documentation"
        direction TB
        Docs["docs/"]:::devops
        TopRead["README.md"]:::devops
        RustRead["README.rust.md"]:::devops
    end

    %% Historical Architecture
    subgraph "Historical Architecture"
        direction TB
        LegacyMonolith["Python Monolith (Legacy)"]:::legacy
    end

    LegacyMonolith -.-> Database

    %% Click Events
    click FrontendService "https://github.com/debugger-demons/whoknows/tree/development/frontend/"
    click StaticAssets "https://github.com/debugger-demons/whoknows/tree/development/frontend/static/"
    click FrontendMain "https://github.com/debugger-demons/whoknows/blob/development/frontend/src/main.rs"
    click FrontendCargo "https://github.com/debugger-demons/whoknows/blob/development/frontend/Cargo.toml"
    click FrontendDockerfile "https://github.com/debugger-demons/whoknows/tree/development/frontend/Dockerfile"
    click FrontendDocs "https://github.com/debugger-demons/whoknows/blob/development/frontend/docs/architecture.md"
    click BackendService "https://github.com/debugger-demons/whoknows/tree/development/backend/"
    click BackMain "https://github.com/debugger-demons/whoknows/blob/development/backend/src/main.rs"
    click BackCargo "https://github.com/debugger-demons/whoknows/blob/development/backend/Cargo.toml"
    click BackDockerfile "https://github.com/debugger-demons/whoknows/tree/development/backend/Dockerfile"
    click BackMigration "https://github.com/debugger-demons/whoknows/blob/development/backend/db-migration/whoknows.tables.sql"
    click BackAPIDocs "https://github.com/debugger-demons/whoknows/blob/development/backend/docs/api.md"
    click BackArchDocs "https://github.com/debugger-demons/whoknows/blob/development/backend/docs/architecture.md"
    click DBSchema "https://github.com/debugger-demons/whoknows/blob/development/database/schema.sql"
    click GHValidate "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/validate.env_and_secrets.yml"
    click GHVerify "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/verify-secret-hash.yml"
    click GHBuild "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/build.yml"
    click GHDev "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/cd.dev.yml"
    click GHProd "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/cd.prod.yml"
    click GHRelease "https://github.com/debugger-demons/whoknows/blob/development/.github/workflows/release.yml"
    click DeploySh "https://github.com/debugger-demons/whoknows/blob/development/deployment/scripts/deploy.sh"
    click LoginSh "https://github.com/debugger-demons/whoknows/blob/development/deployment/scripts/docker-login.sh"
    click SetupSecrets "https://github.com/debugger-demons/whoknows/blob/development/deployment/scripts/setup_gh_secrets.sh"
    click EnvRoot "https://github.com/debugger-demons/whoknows/blob/development/.env.template"
    click EnvBackend "https://github.com/debugger-demons/whoknows/blob/development/backend/.env.local.backend.template"
    click EnvFrontend "https://github.com/debugger-demons/whoknows/blob/development/frontend/.env.local.frontend.template"
    click DCYML "https://github.com/debugger-demons/whoknows/blob/development/docker-compose.yml"
    click DCDev "https://github.com/debugger-demons/whoknows/blob/development/docker-compose.dev.yml"
    click DCProd "https://github.com/debugger-demons/whoknows/blob/development/docker-compose.prod.yml"
    click Docs "https://github.com/debugger-demons/whoknows/tree/development/docs/"
    click TopRead "https://github.com/debugger-demons/whoknows/blob/development/README.md"
    click RustRead "https://github.com/debugger-demons/whoknows/blob/development/README.rust.md"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D6FFD6,stroke:#028a02,color:#028a02
    classDef database fill:#FFE2C6,stroke:#d46e00,color:#d46e00
    classDef devops fill:#E5D3FF,stroke:#6f42c1,color:#6f42c1
    classDef legacy fill:#F0F0F0,stroke:#6a737d,color:#6a737d
```
