# proposals-app/proposalsapp architecture

> Architecture diagram of the GitHub repository proposals-app/proposalsapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/proposals-app/proposalsapp
- Repository: https://github.com/proposals-app/proposalsapp

## Overview

##### Main Components (Top Level)

**Frontend Layer:**
- Web Applications (apps/web and apps/web-arbitrum)
- UI Components (shadcn components)
- Client-side State Management

**Backend Services Layer:**
- Detective Service (Proposal Indexer)
- Discourse Service
- Email Service
- Push Service
- Mapper Service

**Database Layer:**
- SeaORM Models
- Kysely Migrations

##### Key Relationships and Data Flow

**a. Data Collection Flow:**
- Blockchain/External Sources -> Detective Service -> Database
- Discourse Platform -> Discourse Service -> Database

**b. Notification Flow:**
- Database -> Email Service -> Users
- Database -> Push Service -> Users

**c. Frontend Data Flow:**
- Web Apps -> Backend Services -> Database

##### Component Details

**Detective Service:**
- Multiple Chain Indexers (Arbitrum, Ethereum, etc.)
- ABI Handlers
- Chain Data Processors

**Discourse Service:**
- Categories Handler
- Posts Handler
- Users Handler
- Revisions Handler

**Database Schema Groups:**
- DAO-related tables
- User-related tables
- Discourse-related tables
- Voting/Delegation tables

**Authentication Flow:**
- User Sessions
- Email Verification
- Push Notification Subscriptions

**Indexing Pipeline:**
- Proposal Detection
- Vote Tracking
- Discussion Integration

##### Technical Stack Indicators

Technology labels:
**Frontend: Next.js, TypeScript, Tailwind**
**Backend: Rust, SeaORM**
**Services: TypeScript (Email/Push)**
**Database: PostgreSQL (implied by SeaORM)**

##### Cross-Cutting Concerns

Shared components:
- Authentication/Authorization
- Monitoring/Logging
- Configuration Management

##### The notification system architecture

Keep the abstraction level balanced to show both the high-level architecture and important implementation details without overwhelming the viewer.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#3b82f6,color:white
    classDef backend fill:#22c55e,color:white
    classDef database fill:#f97316,color:white
    classDef external fill:#6b7280,color:white

    %% External Services
    ExternalSources[("External Sources")]:::external
    DiscoursePlatform[("Discourse Platform")]:::external

    %% Frontend Layer
    subgraph Frontend
        WebApp["Main Web App"]
        ArbitrumApp["Arbitrum Web App"]
        UIComponents["UI Components"]
        AuthRoutes["Auth Routes"]
    end
    class WebApp,ArbitrumApp,UIComponents,AuthRoutes frontend

    %% Backend Services Layer
    subgraph Services
        Detective["Detective Service"]
        Discourse["Discourse Service"]
        Email["Email Service"]
        Push["Push Service"]
        Mapper["Mapper Service"]
    end
    class Detective,Discourse,Email,Push,Mapper backend

    %% Database Layer
    subgraph Database
        SeaORM["SeaORM Models"]
        Migrations["Kysely Migrations"]
        DAOModels["DAO Models"]
        UserModels["User Models"]
        ProposalModels["Proposal Models"]
        VoteModels["Vote Models"]
    end
    class SeaORM,Migrations,DAOModels,UserModels,ProposalModels,VoteModels database

    %% Indexing Components
    subgraph Indexers
        ChainIndexers["Chain Indexers"]
        DiscourseIndexers["Discourse Indexers"]
    end
    class ChainIndexers,DiscourseIndexers backend

    %% Email Components
    subgraph EmailSystem
        EmailComponents["Email Components"]
        EmailTemplates["Email Templates"]
    end
    class EmailComponents,EmailTemplates backend

    %% Relationships
    ExternalSources --> Detective
    DiscoursePlatform --> Discourse
    Detective --> SeaORM
    Discourse --> SeaORM
    SeaORM --> Email
    SeaORM --> Push
    Email --> EmailComponents
    EmailComponents --> EmailTemplates
    WebApp --> Services
    ArbitrumApp --> Services
    Services --> Database
    Detective --> ChainIndexers
    Discourse --> DiscourseIndexers

    %% Click Events
    click WebApp "https://github.com/proposals-app/proposalsapp/tree/main/apps/web/"
    click ArbitrumApp "https://github.com/proposals-app/proposalsapp/tree/main/apps/web-arbitrum/"
    click UIComponents "https://github.com/proposals-app/proposalsapp/tree/main/apps/web/shadcn/ui/"
    click Detective "https://github.com/proposals-app/proposalsapp/tree/main/apps/detective/"
    click Discourse "https://github.com/proposals-app/proposalsapp/tree/main/apps/discourse/"
    click Email "https://github.com/proposals-app/proposalsapp/tree/main/apps/email-service/"
    click Push "https://github.com/proposals-app/proposalsapp/tree/main/apps/push-service/"
    click Mapper "https://github.com/proposals-app/proposalsapp/tree/main/apps/mapper/"
    click SeaORM "https://github.com/proposals-app/proposalsapp/tree/main/libs/rust/seaorm/src/"
    click Migrations "https://github.com/proposals-app/proposalsapp/tree/main/libs/ts/db/migrations/"
    click ChainIndexers "https://github.com/proposals-app/proposalsapp/tree/main/apps/detective/indexers/"
    click DiscourseIndexers "https://github.com/proposals-app/proposalsapp/tree/main/apps/discourse/indexers/"
    click EmailComponents "https://github.com/proposals-app/proposalsapp/tree/main/libs/ts/emails/components/"
    click EmailTemplates "https://github.com/proposals-app/proposalsapp/tree/main/libs/ts/emails/emails/"
    click AuthRoutes "https://github.com/proposals-app/proposalsapp/tree/main/apps/web/app/api/auth/"
    click DAOModels "https://github.com/proposals-app/proposalsapp/blob/main/libs/rust/seaorm/src/dao.rs"
    click UserModels "https://github.com/proposals-app/proposalsapp/blob/main/libs/rust/seaorm/src/user.rs"
    click ProposalModels "https://github.com/proposals-app/proposalsapp/blob/main/libs/rust/seaorm/src/proposal.rs"
    click VoteModels "https://github.com/proposals-app/proposalsapp/blob/main/libs/rust/seaorm/src/vote.rs"

    %% Legend
    subgraph Legend
        Frontend_L["Frontend"]:::frontend
        Backend_L["Backend Services"]:::backend
        Database_L["Database"]:::database
        External_L["External Services"]:::external
    end
```
