# jerlendds/osintbuddy architecture

> Architecture diagram of the GitHub repository jerlendds/osintbuddy, 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/jerlendds/osintbuddy
- Repository: https://github.com/jerlendds/osintbuddy

## Overview

##### Key Components
- Frontend:
– Built with React/TypeScript (located in the “frontend” directory).
– Contains multiple UI routes, React components, and uses Tailwind, module federation, and other modern web technologies.
– Connects to the backend API via HTTP requests.

- Backend:
– Located in “backend/app/app”. It is a Python-based API (likely using FastAPI) serving versioned REST endpoints (api_v1) for operations such as account management, entity processing, graphs, login, scans, and more.
– Contains modules for dependencies, configuration, and CRUD operations.
– Uses Alembic migrations to handle the database schema changes.
– Integrates asynchronous processing through Celery workers (files like “celeryworker_pre_start.py”, “worker.py”).
– Handles business logic, email template processing, locales, and session management.

- Database & Graph Storage:
– The backend uses Alembic for migrations which implies a relational database. Also, based on the README, there is an ongoing refactor from JanusGraph (and its dependent services such as Solr and ScyllaDB) toward using Apache Age on PostgreSQL.

- Authentication & External Services:
– Casdoor is integrated for authentication (files like “casdoor.py” in core indicate this).
– External services such as the authentication portal, as well as potential data-fetching and monitoring endpoints, should be noted.

- Orchestration & Deployment:
– The “launcher” script provides Docker compose commands to bootstrap and manage the entire stack.
– Several Dockerfiles (backend/backend.Dockerfile, worker.Dockerfile) indicate containerized deployment.
– The “ob” directory contains environment configurations, integration scripts (for JanusGraph, SeaweedFS), and other orchestration artifacts.
– Represent Docker containers (or services) such as the API backend container, frontend container, worker container, and supporting data services.

- Plugin System:
– OSINTBuddy is designed to allow Python developers to make plugins (see references to “osintbuddy-plugins”).

##### Relationships and Interactions
- A connection between the Backend and the Casdoor authentication service for token validation and user login functionality.
- Optionally, show connections to external monitoring or email services if applicable.

##### Architectural Patterns and Technologies
- Separation of concerns:
– Frontend (UI and routing)
– Backend API logic (versioned endpoints)
– Data persistence (relational/graph storage via PostgreSQL/Apache Age suite)
– Asynchronous processing (via Celery workers).
- Mention that the microservices or modular approach (such as plugin extensibility, API versioning, and potential container orchestration) is central to the architecture.
- Dependencies such as FastAPI, Alembic, Celery in the backend and React with module federation on the frontend.

– Plugin System: a component labeled “Plugin Integrations” linking to the backend.
– Frontend → Backend API (show “HTTP Requests / REST API”)
– Backend → Database (show “CRUD, Graph Queries”)
– Backend → Celery Worker (for async tasks)
– Backend ↔ Casdoor (for authentication flows)
- Adding notes or annotations next to components that highlight future architectural changes – such as the transition from JanusGraph to Apache Age.

##### Final Reminder
- As many details as possible without overcomplicating—the goal is to clearly represent all essential architectural elements.
- Every component and its interactions are represented with clarity so that any new contributor or stakeholder can understand how the system is organized and how data flows throughout.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Container/Orchestration Layer
    H["Container/Orchestration"]:::container

    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Frontend – React/TypeScript UI"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B["Backend – Python/FastAPI"]:::backend
        B1["Versioned REST Endpoints (api_v1)"]:::backend
        E["Celery Worker"]:::async
        F["Casdoor Authentication"]:::auth
        G["Plugin Integrations"]:::plugin
        %% Internal connection within Backend
        B -->|"API_v1"| B1
        %% Backend interactions
        B -->|"Async_Tasks"| E
        B -->|"Auth_Flow"| F
        B -->|"Plugin_Extension"| G
    end

    %% Data Layer
    subgraph "Data Layer"
        D2["Database Migrations (Alembic)"]:::data
        D["Relational/Graph Database (PostgreSQL with Apache Age)"]:::data
        D2 -->|"schema_migrations"| D
    end

    %% Interactions between layers
    A -->|"HTTP_Requests"| B
    B -->|"CRUD&Graph_Queries"| D
    E -->|"Updates_DB"| D
    F ---|"Auth_Flow"| B

    %% Container orchestration managing services
    H -->|"Manages"| A
    H -->|"Manages"| B
    H -->|"Manages"| E
    H -->|"Manages"| D

    %% Click Events
    click A "https://github.com/jerlendds/osintbuddy/tree/main/frontend/"
    click B "https://github.com/jerlendds/osintbuddy/tree/main/backend/app/app/"
    click B1 "https://github.com/jerlendds/osintbuddy/tree/main/backend/app/app/api/api_v1/"
    click D2 "https://github.com/jerlendds/osintbuddy/tree/main/backend/app/alembic/"
    click E "https://github.com/jerlendds/osintbuddy/blob/main/backend/app/app/worker.py"
    click E "https://github.com/jerlendds/osintbuddy/blob/main/backend/app/app/celeryworker_pre_start.py"
    click F "https://github.com/jerlendds/osintbuddy/blob/main/backend/app/app/core/casdoor.py"
    click G "https://github.com/jerlendds/osintbuddy/tree/main/backend/osintbuddy-plugins"
    click H "https://github.com/jerlendds/osintbuddy/tree/main/launcher"
    click H "https://github.com/jerlendds/osintbuddy/blob/main/backend/backend.Dockerfile"
    click H "https://github.com/jerlendds/osintbuddy/blob/main/backend/worker.Dockerfile"
    click H "https://github.com/jerlendds/osintbuddy/tree/main/ob/"

    %% Styles
    classDef frontend fill:#fceabb,stroke:#e48a1c,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef async fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef auth fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef plugin fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef data fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef container fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
```
