# muni-town/pigeon architecture

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

- Interactive diagram: https://gitdiagram.com/muni-town/pigeon
- Repository: https://github.com/muni-town/pigeon

## Overview

##### Main Components

a. Client-Side Application Structure:
- Frontend SPA (Single Page Application)
- React Components Layer
- State Management Layer (using atoms pattern)
- Matrix Client Integration Layer

b. Core Features:
- Authentication System
- Real-time Communication
- File/Media Handling
- Encryption Support
- Internationalization (i18n)

##### Key Architectural Patterns to Highlight

a. Component Architecture:
- Atomic Design Pattern (evident from the /atoms, /molecules, /organisms folders)
- Feature-based Organization (seen in /features directory)
- Custom Hooks Layer (/hooks directory)

b. State Management:
- Atomic State Management
- Matrix Client State
- Room/Space Management

##### Integration Points

a. External Services:
- Matrix Server Communication
- Media Storage
- Push Notifications

b. Browser Integration:
- Service Worker
- Local Storage
- IndexedDB

##### Specific Implementation Details

**┌─────────────────────────────────────────────────────────┐**
- UI Layer                             │
- ┬─────────────────┬───────────────────┤
- Atoms        │    Molecules    │     Organisms     │
- (Base UI)      │  (Compositions) │   (Features)      │
- ┴─────────────────┴───────────────────┤
- Features Layer                         │
- ┤
- State Management                        │
- ┤
- Matrix Client Layer                     │
- ┤
- Utils & Helpers                         │
- ┘

##### Data Flow Indicators

- Bidirectional communication with Matrix servers
- State updates flow
- Encryption/decryption paths
- Media upload/download flows

##### Additional Elements

- Version compatibility notes
- Security boundaries
- Scale-out possibilities

##### Deployment Context

- How it works within nginx
- Static file serving
- API endpoints
- Where configuration can be customized

- The clean separation of concerns
- The atomic design pattern implementation
- The security-first approach
- The real-time nature of the application
- The extensibility points

Remember to maintain a balance between detail and clarity, focusing on the architectural decisions that make Cinny unique, such as its security features and elegant UI architecture.

This system design should help developers understand both the high-level architecture and the specific implementation details that make Cinny work effectively as a Matrix client.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI
        App["Frontend SPA"]:::frontend
        click App "https://github.com/muni-town/pigeon/blob/dev/src/app/pages/App.tsx"
        
        subgraph AtomicDesign
            Atoms["Atoms (Base UI)"]:::ui
            Molecules["Molecules (Compositions)"]:::ui
            Organisms["Organisms (Features)"]:::ui
            click Atoms "https://github.com/muni-town/pigeon/tree/dev/src/app/atoms/"
            click Molecules "https://github.com/muni-town/pigeon/tree/dev/src/app/molecules/"
            click Organisms "https://github.com/muni-town/pigeon/tree/dev/src/app/organisms/"
        end
        
        subgraph Features
            RoomFeatures["Room Features"]:::feature
            LobbyFeatures["Lobby Features"]:::feature
            MessageSearch["Message Search"]:::feature
            click RoomFeatures "https://github.com/muni-town/pigeon/tree/dev/src/app/features/room/"
            click LobbyFeatures "https://github.com/muni-town/pigeon/tree/dev/src/app/features/lobby/"
            click MessageSearch "https://github.com/muni-town/pigeon/tree/dev/src/app/features/message-search/"
        end
    end

    subgraph Auth
        AuthSystem["Authentication System"]:::auth
        Login["Login"]:::auth
        Register["Registration"]:::auth
        PasswordReset["Password Reset"]:::auth
        click AuthSystem "https://github.com/muni-town/pigeon/tree/dev/src/app/pages/auth/"
        click Login "https://github.com/muni-town/pigeon/tree/dev/src/app/pages/auth/login/"
        click Register "https://github.com/muni-town/pigeon/tree/dev/src/app/pages/auth/register/"
        click PasswordReset "https://github.com/muni-town/pigeon/tree/dev/src/app/pages/auth/reset-password/"
    end

    subgraph State
        StateManagement["State Management"]:::state
        MatrixState["Matrix State"]:::state
        click StateManagement "https://github.com/muni-town/pigeon/tree/dev/src/app/state/"
        click MatrixState "https://github.com/muni-town/pigeon/tree/dev/src/client/state/"
    end

    subgraph Integration
        MatrixClient["Matrix Client"]:::integration
        MatrixActions["Matrix Actions"]:::integration
        click MatrixClient "https://github.com/muni-town/pigeon/tree/dev/src/client/"
        click MatrixActions "https://github.com/muni-town/pigeon/tree/dev/src/client/action/"
    end

    subgraph Media
        MediaHandling["Media Components"]:::media
        UploadBoard["Upload Components"]:::media
        ImageViewer["Image Viewer"]:::media
        click MediaHandling "https://github.com/muni-town/pigeon/tree/dev/src/app/components/media/"
        click UploadBoard "https://github.com/muni-town/pigeon/tree/dev/src/app/components/upload-board/"
        click ImageViewer "https://github.com/muni-town/pigeon/tree/dev/src/app/components/image-viewer/"
    end

    subgraph Security
        E2EKeys["E2E Room Keys"]:::security
        RoomEncryption["Room Encryption"]:::security
        CryptoUtils["Crypto Utils"]:::security
        click E2EKeys "https://github.com/muni-town/pigeon/tree/dev/src/app/molecules/import-export-e2e-room-keys/"
        click RoomEncryption "https://github.com/muni-town/pigeon/tree/dev/src/app/molecules/room-encryption/"
        click CryptoUtils "https://github.com/muni-town/pigeon/blob/dev/src/util/cryptE2ERoomKeys.js"
    end

    subgraph Browser
        ServiceWorker["Service Worker"]:::browser
        MediaConfig["Media Config"]:::browser
        click ServiceWorker "https://github.com/muni-town/pigeon/blob/dev/src/sw.ts"
        click MediaConfig "https://github.com/muni-town/pigeon/blob/dev/src/app/components/MediaConfigLoader.tsx"
    end

    subgraph i18n
        I18nConfig["i18n Configuration"]:::i18n
        LocaleFiles["Locale Files"]:::i18n
        click I18nConfig "https://github.com/muni-town/pigeon/blob/dev/src/app/i18n.ts"
        click LocaleFiles "https://github.com/muni-town/pigeon/tree/dev/public/locales/"
    end

    %% Relationships
    App --> AtomicDesign
    App --> Features
    App --> Auth
    App --> State
    MatrixClient --> MatrixState
    MatrixActions --> MatrixState
    StateManagement --> Features
    Auth --> MatrixClient
    Features --> Media
    Features --> Security
    App --> I18nConfig
    ServiceWorker --> App
    MediaConfig --> Media

    %% Styles
    classDef frontend fill:#e1f5fe,stroke:#01579b
    classDef ui fill:#e8f5e9,stroke:#2e7d32
    classDef feature fill:#fff3e0,stroke:#ff6f00
    classDef auth fill:#f3e5f5,stroke:#7b1fa2
    classDef state fill:#fff8e1,stroke:#ffa000
    classDef integration fill:#fbe9e7,stroke:#d84315
    classDef media fill:#e0f2f1,stroke:#00695c
    classDef security fill:#ffebee,stroke:#c62828
    classDef browser fill:#f3e5f5,stroke:#6a1b9a
    classDef i18n fill:#e8eaf6,stroke:#283593
```
