# believer-oss/ethos architecture

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

- Interactive diagram: https://gitdiagram.com/believer-oss/ethos
- Repository: https://github.com/believer-oss/ethos

## Overview

##### Project Type and Purpose
- This is a collection of desktop applications designed for game development teams, where one tool (Friendshipper) targets managing builds, playtesting, and Git-based version interactions (with separate modes for contributors and playtesting), and the other (Birdie) targets asset management through Git LFS.
- The project also includes shared code (in the “core” directory) that provides common Git integrations, configuration management, middleware, and utility functions across the tools.

##### Analyzing the File Structure
- Notice that top-level directories include “birdie”, “friendshipper”, and “core” as well as shared configuration files (Docker, Cargo, etc.). These identify three high-level components:
- The individual applications (Friendshipper and Birdie),
- The shared core library (likely “ethos-core” as referenced in the README),
- Supporting assets and configuration (global configs, GitHub workflows, etc.).
- Inside each app directory (e.g., “friendshipper” and “birdie”), there is a typical Tauri structure: a “src-tauri” folder with Rust code (commands, configuration, repository operations, system interactions) and a “src” folder for the Svelte frontend. This clearly shows adoption of a frontend-backend split within each desktop application.
- The “core” directory contains a Cargo project with modules for authentication, Git client operations, storage (even for Git LFS), middleware, and various common utilities.

##### Architecture Components
a. Main Components:
- UI / Frontend Layer – Designed with Svelte/SvelteKit and Flowbite Svelte. These are depicted as the presentation layer for user interactions.
- Tauri-based Application Shell / Backend – Built in Rust. This layer exposes commands (for Git operations, repository actions, build retrieval, playtesting orchestration, asset management) and bridges the UI with the underlying system.
- Shared Core Library (“ethos-core”) – This contains common logic, Git-related operations, authentication flows, middleware, and tooling utilities that are used by both applications.
- External Systems – Represent Git repositories (with Git LFS for assets), external services (AWS, GitHub, Kubernetes, etc.) as referenced in the “core” clients and types directories.
- Configuration and Deployment – Include config files (like tauri.conf.json, dynamic-config.json) and Docker/CI pipelines (as seen in the GitHub workflows) that manage build and deployment operations.

b. Relationships and Interactions:
- The Tauri backend layers call functions/methods from the shared core library for operations like authentication, Git operations, and file storage management.
- Each application might have specific routers and configuration modules (as evidenced in the “router” files under each “repo” or “system” sub-directory) that define the internal workflow.

c. Architectural Patterns and Design Principles:
- The frontend-backend separation in each desktop app aligns with the typical Tauri design: a thin JavaScript-based UI layer that calls a heavyweight Rust backend.
- Common functionalities are factored into a shared “core” crate that multiple desktop apps use, reducing code duplication.
- The directory structure shows a modular design with a clear separation of concerns (authentication, repo operations, configuration, middleware, etc.).
- Use of configuration files and build scripts indicates a pattern for continuous integration/deployment and modular configuration management.

d. Technologies and Frameworks:
- Tauri for desktop application framework (Rust based).
- Svelte and SvelteKit for building the UI.
- Flowbite Svelte for UI components.
- Rust’s Cargo-y structured projects for the backend.
- Git and Git LFS for version control and asset distribution.
- External integrations with AWS, GitHub, and possibly Kubernetes as reflected in the “clients” modules of the core crate.

- Tauri Backend (detailing command handlers, configuration, and system operations for each application)
- Core Library (the shared “ethos-core” crate with sub-modules like auth, clients, middleware, storage)
- External Services (Git repositories, external APIs, AWS clients, GitHub integrations)
- Additional notes or legends noting technology choices (e.g., annotate “Tauri (Rust)” for backend components and “Svelte/SvelteKit (TypeScript)” for frontend components).

## Diagram (Mermaid)

```mermaid
graph TD

  %% Desktop Applications
  subgraph "Friendshipper Application"
    F_UI["Friendshipper UI (Svelte/SvelteKit)"]:::ui
    F_BE["Friendshipper Backend (Tauri/Rust)"]:::backend
    F_UI -->|"UI_requests"| F_BE
  end

  subgraph "Birdie Application"
    B_UI["Birdie UI (Svelte/SvelteKit)"]:::ui
    B_BE["Birdie Backend (Tauri/Rust)"]:::backend
    B_UI -->|"UI_requests"| B_BE
  end

  %% Shared Components
  subgraph "Shared Components"
    CoreLib["Shared Core Library (ethos-core)"]:::core
    UI_Comp["Shared UI Components & Tools"]:::ui
  end

  %% Configuration and Deployment
  subgraph "Configuration & Deployment"
    CW["GitHub Workflows"]:::config
    DC["Dynamic Config"]:::config
  end

  %% External Integrations
  Externals["External Services (Git, AWS, GitHub,GitLFS)"]:::external

  %% Relationships
  F_BE -->|"calls_shared"| CoreLib
  B_BE -->|"calls_shared"| CoreLib
  UI_Comp -->|"used_by"| F_UI
  UI_Comp -->|"used_by"| B_UI

  F_BE -->|"reads_config"| CW
  B_BE -->|"reads_config"| CW
  F_BE -->|"reads_config"| DC
  B_BE -->|"reads_config"| DC

  CoreLib -->|"integrates_with"| Externals

  %% Click Events
  click F_UI "https://github.com/believer-oss/ethos/tree/main/friendshipper/src"
  click F_BE "https://github.com/believer-oss/ethos/tree/main/friendshipper/src-tauri"
  click B_UI "https://github.com/believer-oss/ethos/tree/main/birdie/src"
  click B_BE "https://github.com/believer-oss/ethos/tree/main/birdie/src-tauri"
  click CoreLib "https://github.com/believer-oss/ethos/tree/main/core"
  click UI_Comp "https://github.com/believer-oss/ethos/tree/main/core/ui"
  click CW "https://github.com/believer-oss/ethos/tree/main/.github/workflows"
  click DC "https://github.com/believer-oss/ethos/blob/main/config/dynamic-config.json"

  %% Styles
  classDef ui fill:#AEDFF7,stroke:#0277BD,stroke-width:2px;
  classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
  classDef core fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
  classDef config fill:#F8BBD0,stroke:#D81B60,stroke-width:2px;
  classDef external fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
```
