# thetnaingtn/memos architecture

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

- Interactive diagram: https://gitdiagram.com/thetnaingtn/memos
- Repository: https://github.com/thetnaingtn/memos

## Overview

##### Main Components
- Backend Server: Represent the Go “server” directory. Note its subcomponents such as the API router (server/router/api/v1), runners (for tasks like memopayload and s3presign), and version/profile management.
- Plugins: Show the different plugin categories (cron, filter, httpgetter, idp, storage, webhook) as modular extension points. Indicate that these plugins extend the core functionality (e.g., scheduling tasks or handling external integrations).
- Proto API: Include a component for the API specifications (proto folder) and generated code (proto/gen). This illustrates how service definitions map to gRPC/REST endpoints.
- Data Store: Illustrate the store layer that handles database interactions. Mention the support for multiple database backends (MySQL, Postgres, SQLite), migration scripts (located in store/migration and store/seed), and caching.
- Frontend: Include the “web” directory that contains the React-based user interface, its routing, state management (store/v1, store/v2), and theming. Note that this separates user interaction concerns from the backend logic.
- External Interfaces: Mark Docker configuration (Dockerfile, dockerignore) and CI/CD pipelines (in .github/workflows) showing deployment infrastructure. Additionally, note that the self-hosted nature means that external access could be via API endpoints.

##### Relationships and Interactions
- API Communication: Demonstrate how the backend uses protocol definitions (proto) to structure communication, ensuring consistency between services.
- Plugin & Core Integration: Indicate that plugins integrate into the main application flow to handle tasks like scheduling or external HTTP requests.
- Data Storage: Show that the backend server interacts with the data store layer (store) that abstracts multiple SQL databases. Also include migration and seeding processes for database setup.

##### Architectural Patterns & Design Principles
- Layered Architecture: Separate concerns clearly into presentation (web frontend), business logic (server/router, runners), persistence (store), and extension (plugins).
- Modularity & Extensibility: Emphasize how the plugin system allows for features to be added or modified without altering core components.
- API-First Approach: With defined proto files and generated code, the system enforces a contract between services.
- CI/CD Integration: Reflect the importance of automated testing and deployment as indicated by the GitHub workflows and Docker setup files.

##### Relevant Technologies & Frameworks
- Go as the primary backend language.
- React and TypeScript (with Vite and Tailwind CSS) for the frontend.
- gRPC/Protocol Buffers for API definition and communication.
- SQL databases (MySQL, Postgres, SQLite) with migration support.
- Docker for containerization and deployment.
- CI/CD tools (GitHub Actions) for build, testing, and deployment automation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Frontend - React App"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B["Backend - Go Server"]:::backend
        C["API Router (v1)"]:::backend
        D["Runner: memopayload"]:::backend
        E["Runner: s3presign"]:::backend
        F["Version Management"]:::backend
        G["Profile Management"]:::backend
    end

    %% Plugins Layer
    subgraph "Plugins Layer"
        H["Plugin - Cron"]:::plugin
        I["Plugin - Filter"]:::plugin
        J["Plugin - HttpGetter"]:::plugin
        K["Plugin - IDP"]:::plugin
        L["Plugin - Storage"]:::plugin
        M["Plugin - Webhook"]:::plugin
    end

    %% Proto API
    subgraph "Proto API"
        N["Proto Specifications"]:::proto
        O["Generated Code"]:::proto
    end

    %% Data Store
    subgraph "Data Store"
        P["Store Core"]:::store
        Q["Database Interfaces"]:::store
        R["Migration Scripts"]:::store
        S["Seed Data"]:::store
    end

    %% External Interfaces
    subgraph "External Interfaces"
        T1["Dockerfile"]:::external
        T2[".dockerignore"]:::external
        U["CI/CD Pipelines"]:::external
    end

    %% Relationships / Data Flow
    A -->|"HTTP/gRPC"| C
    C --> B
    B --> D
    B --> E
    B --> F
    B --> G
    B -->|"uses"| N
    B -->|"uses"| O
    B -->|"integrates"| H
    B -->|"integrates"| I
    B -->|"integrates"| J
    B -->|"integrates"| K
    B -->|"integrates"| L
    B -->|"integrates"| M
    B -->|"DB interaction"| P
    P --> Q
    P --> R
    P --> S
    T1 -->|"deployment"| B
    T1 -->|"deployment"| A
    T2 -->|"deployment"| B
    T2 -->|"deployment"| A
    U -->|"CI/CD"| B
    U -->|"CI/CD"| A

    %% Click Events for Backend Components
    click B "https://github.com/thetnaingtn/memos/tree/main/server"
    click C "https://github.com/thetnaingtn/memos/tree/main/server/router/api/v1"
    click D "https://github.com/thetnaingtn/memos/tree/main/server/runner/memopayload"
    click E "https://github.com/thetnaingtn/memos/tree/main/server/runner/s3presign"
    click F "https://github.com/thetnaingtn/memos/tree/main/server/version"
    click G "https://github.com/thetnaingtn/memos/tree/main/server/profile"

    %% Click Events for Plugins
    click H "https://github.com/thetnaingtn/memos/tree/main/plugin/cron"
    click I "https://github.com/thetnaingtn/memos/tree/main/plugin/filter"
    click J "https://github.com/thetnaingtn/memos/tree/main/plugin/httpgetter"
    click K "https://github.com/thetnaingtn/memos/tree/main/plugin/idp"
    click L "https://github.com/thetnaingtn/memos/tree/main/plugin/storage"
    click M "https://github.com/thetnaingtn/memos/tree/main/plugin/webhook"

    %% Click Events for Proto API
    click N "https://github.com/thetnaingtn/memos/tree/main/proto"
    click O "https://github.com/thetnaingtn/memos/tree/main/proto/gen"

    %% Click Events for Data Store
    click P "https://github.com/thetnaingtn/memos/tree/main/store"
    click Q "https://github.com/thetnaingtn/memos/tree/main/store/db"
    click R "https://github.com/thetnaingtn/memos/tree/main/store/migration"
    click S "https://github.com/thetnaingtn/memos/tree/main/store/seed"

    %% Click Event for Frontend
    click A "https://github.com/thetnaingtn/memos/tree/main/web"

    %% Click Events for External Interfaces
    click T1 "https://github.com/thetnaingtn/memos/tree/main/Dockerfile"
    click T2 "https://github.com/thetnaingtn/memos/blob/main/.dockerignore"
    click U "https://github.com/thetnaingtn/memos/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef plugin fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef proto fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef store fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#FFFFE0,stroke:#000,stroke-width:2px;
```
