# algora-io/algora architecture

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

- Interactive diagram: https://gitdiagram.com/algora-io/algora
- Repository: https://github.com/algora-io/algora

## Overview

##### Project type and purpose
- This is a full-stack Elixir/Phoenix application (lib/algora + lib/algora_web) with an integrated GitHub App and payment processor.
- Business logic lives in `lib/algora` (contexts: accounts, activities, bounties, chat, payments, workspace, etc.). The web UI and API are in `lib/algora_web` (LiveView, controllers, components).
- Static content and docs are in `priv/content`. Asset building uses Node.js + Svelte + Tailwind (assets/). Background jobs use Oban.

##### File structure
- Top-level directories:
- assets/ → front-end build (Svelte components, TS, CSS, JS)
- config/ → environment configs for dev/prod/test
- lib/algora/ → core contexts and domain logic
- lib/algora_web/ → Phoenix endpoint, router, controllers, LiveView, components, plugs
- priv/repo/ → Ecto migrations & seeds
- rel/ → release scripts (Distillery or Mix releases)
- test/ → ExUnit tests for contexts, web, integrations
- Key config: `Dockerfile`, `fly.toml`, `.env.example` for external service keys (GitHub, Stripe, S3, Cloudflare Tunnel).
- Background work: Oban jobs in multiple contexts (activities/jobs, bounties/jobs, workspace/jobs, etc.).

##### README for additional insights
- Describes three “apps” in one codebase: Web app, GitHub App, Payment engine.
- Uses Docker/Postgres in dev, external dependencies: GitHub webhooks & polling, Stripe webhooks, S3 for static assets, Cloudflare Tunnel for local webhooks.

##### Detail but avoid clutter
- Every major context only if it clarifies data flow (e.g. Accounts, Bounties, Chat can be sub-contexts).
- Core paths: user login, bounty creation, tip sending, job application, webhook handling, payment flow.
- Oban queue with examples of jobs (send_email, notify_discord).
- Call out the Poller supervisor under GitHub integration to show event-driven vs. webhook flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client & Assets
    subgraph "Client Layer" 
        direction TB
        Browser["Client (Browser)"]:::client
        Assets["Asset Build Pipeline"]:::client
    end

    %% Phoenix Layer
    subgraph "Phoenix Web Server" 
        direction TB
        EP["Endpoint"]:::backend
        RT["Router"]:::backend
        UI["Controllers & LiveViews"]:::backend
    end

    %% Domain & Workers
    subgraph "Domain Layer (lib/algora)" 
        direction TB
        Domain["Contexts & Business Logic"]:::backend
        subgraph "Oban Workers"
            direction TB
            JobsCore["Jobs API"]:::workers
            ActJobs["Activities Jobs"]:::workers
            BntJobs["Bounties Jobs"]:::workers
            PmtJobs["Payments Jobs"]:::workers
            WspJobs["Workspace Jobs"]:::workers
        end
    end

    %% Database
    subgraph "Database"
        direction TB
        RepoNode["Ecto Repo"]:::db
        DB["Postgres DB"]:::db
        Migrations["Migrations & Seeds"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        subgraph "GitHub Integration"
            direction TB
            GHBehaviour["Behaviour"]:::external
            GHClient["Client"]:::external
            GHPoller["Poller Supervisors"]:::external
            GHWebHook["Webhook Handler"]:::external
        end
        subgraph "Stripe Integration"
            direction TB
            PSP["PSP Adapter"]:::external
            PmtContext["Payments Context"]:::external
            StripeHook["Stripe Webhook Handler"]:::external
        end
        S3["S3 Static Asset Storage"]:::external
        Tunnel["Tunnel Service"]:::external
        StaticDocs["Static Content & Docs"]:::external
    end

    %% Config & Releases
    subgraph "Config & Releases"
        direction TB
        DockerfileNode["Dockerfile & env"]:::config
        Release["Release Scripts"]:::config
    end

    %% Connections
    Browser <--> EP
    Assets --> EP
    EP --> RT
    RT --> UI
    UI --> Domain
    Domain --> RepoNode
    Domain --> JobsCore
    JobsCore --> DB
    ActJobs --> DB
    BntJobs --> DB
    PmtJobs --> DB
    WspJobs --> DB
    Domain --> GHBehaviour
    Domain --> PSP
    GHBehaviour --> GHClient
    GHClient --> GHPoller
    GHPoller --> Domain
    GitHubEvents["GitHub Webhooks"]:::external
    StripeEvents["Stripe Webhooks"]:::external

    GitHubEvents --> Tunnel --> GHWebHook --> Domain
    StripeEvents --> Tunnel --> StripeHook --> Domain
    Domain --> S3
    UI --> StaticDocs
    Domain --> Migrations

    %% Click Events
    click Assets "https://github.com/algora-io/algora/tree/main/assets/"
    click EP "https://github.com/algora-io/algora/blob/main/lib/algora_web/endpoint.ex"
    click RT "https://github.com/algora-io/algora/blob/main/lib/algora_web/router.ex"
    click UI "https://github.com/algora-io/algora/tree/main/lib/algora_web/"
    click Domain "https://github.com/algora-io/algora/tree/main/lib/algora/"
    click JobsCore "https://github.com/algora-io/algora/blob/main/lib/algora/jobs/jobs.ex"
    click ActJobs "https://github.com/algora-io/algora/tree/main/lib/algora/activities/jobs/"
    click BntJobs "https://github.com/algora-io/algora/tree/main/lib/algora/bounties/jobs/"
    click PmtJobs "https://github.com/algora-io/algora/tree/main/lib/algora/payments/jobs/"
    click WspJobs "https://github.com/algora-io/algora/tree/main/lib/algora/workspace/jobs/"
    click RepoNode "https://github.com/algora-io/algora/blob/main/lib/algora/repo.ex"
    click Migrations "https://github.com/algora-io/algora/tree/main/priv/repo/"
    click GHBehaviour "https://github.com/algora-io/algora/blob/main/lib/algora/integrations/github/behaviour.ex"
    click GHClient "https://github.com/algora-io/algora/blob/main/lib/algora/integrations/github/client.ex"
    click GHPoller "https://github.com/algora-io/algora/tree/main/lib/algora/integrations/github/poller/"
    click GHWebHook "https://github.com/algora-io/algora/blob/main/lib/algora_web/controllers/webhooks/github_controller.ex"
    click PSP "https://github.com/algora-io/algora/tree/main/lib/algora/psp/"
    click PmtContext "https://github.com/algora-io/algora/blob/main/lib/algora/payments/payments.ex"
    click StripeHook "https://github.com/algora-io/algora/blob/main/lib/algora_web/controllers/webhooks/stripe_controller.ex"
    click S3 "https://github.com/algora-io/algora/blob/main/lib/algora/s3.ex"
    click Tunnel "https://github.com/algora-io/algora/blob/main/lib/algora/integrations/tunnel.ex"
    click StaticDocs "https://github.com/algora-io/algora/tree/main/priv/content/"
    click DockerfileNode "https://github.com/algora-io/algora/tree/main/Dockerfile"
    click Release "https://github.com/algora-io/algora/tree/main/rel/"

    %% Styles
    classDef client fill:#a2f7a1,stroke:#333,stroke-width:1px
    classDef backend fill:#afe3ff,stroke:#333,stroke-width:1px
    classDef workers fill:#ffd699,stroke:#333,stroke-width:1px
    classDef db fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
```
