Agora Architecture & Protocols

This document describes the architectural patterns and protocols used in the Agora, specifically focusing on the interaction between components (Server, Bridge) and external systems (Fediverse).

1. The Signup Protocol (Client -> Server -> Bridge)

The "Join" flow allows users to self-onboard by adding their Git repositories to the Agora.

Components

• Client: The JavaScript frontend (settings.ts, overlay.html).
• Agora Server: The main Flask application (agora.py), serving as the public gateway.
• Agora Bridge: An internal microservice (api/agora.py) running on a private port (default: 5018). It has privileged access to the filesystem and configuration.

Sequence Diagram

sequenceDiagram
    participant User
    participant Browser as Client (Browser)
    participant Server as Agora Server (5017)
    participant Bridge as Agora Bridge (5018)
    participant FS as File System

    User->>Browser: Enters Username & Repo URL, clicks "Join"
    
    Browser->>Server: POST /api/join {username, repo_url}
    
    Note over Server: 1. Validate Input<br/>2. Construct target path (garden/user)<br/>3. Resolve Bridge URL (config)
    
    Server->>Bridge: POST /sources {url, target, type='garden', format='git'}
    
    Note over Bridge: 1. Read ~/agora/sources.yaml<br/>2. Check for duplicates<br/>3. Append new source<br/>4. Write sources.yaml
    
    Bridge->>FS: git clone <repo_url> ~/agora/<target>
    FS-->>Bridge: (Exit Code / Output)
    
    alt Clone Success
        Bridge-->>Server: 201 Created {message: "Source added and cloned"}
        Server-->>Browser: 200 OK {message: "Success! You have joined."}
        Browser->>User: Displays "Success!" (Green)
    else Clone Failure
        Bridge-->>Server: 202 Accepted {error: "Git error...", source: ...}
        Server-->>Browser: 200 OK {message: "Added, but clone failed. Contact admin."}
        Browser->>User: Displays Error/Warning
    end

2. The Federation Protocol (Content Broadcasting)

The Agora acts as an ActivityPub instance (anagora.org). It periodically broadcasts new content to its followers.

Components

• Federation Loop: A background thread in Agora Server (federate_latest_loop).
• Git Utils: Helper module (git_utils.py) to query git history.
• SQLite: The database storing federation state (federated_subnodes, followers).

Sequence Diagram

sequenceDiagram
    participant Loop as Federation Loop (Thread)
    participant Git as Git Utils
    participant DB as SQLite
    participant AP as ActivityPub Followers

    Note over Loop: Runs every 5 minutes (or 10s in debug)

    Loop->>Git: get_latest_changes_per_repo()
    Git-->>Loop: [User: [Subnode A, Subnode B...], ...]
    
    loop For each Subnode
        Loop->>DB: Check is_subnode_federated(uri)
        
        opt Not Federated
            Note over Loop: 1. Render Content (or handle Image)<br/>2. Construct 'Create' Activity<br/>3. Load RSA Keys
            
            Loop->>DB: Get Followers of Author (or @agora)
            
            loop For each Follower
                Loop->>AP: Resolve Inbox URL (WebFinger/Actor fetch)
                Loop->>AP: POST /inbox (Signed 'Create' Activity)
            end
            
            Loop->>DB: add_federated_subnode(uri)
        end
    end

3. Bridge Interface Specification

The Agora Bridge provides a RESTful interface for privileged operations.

Base URL: http://localhost:5018 (Internal)

Endpoint	Method	Payload	Description
/	GET	-	Status Page. Returns HTML listing configured sources and database stats.
/sources	POST	url: Git URL target: Path slug type: ‘garden’|’stoa’ format: ‘git’ (default)	Add Source. updates sources.yaml and triggers a synchronous git clone.

---

*Generated by Gemini for Agora Docs, 2025-12-14.*