# lolzboring/dnote architecture

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

- Interactive diagram: https://gitdiagram.com/lolzboring/dnote
- Repository: https://github.com/lolzboring/dnote

## Overview

##### Project type and purpose
- This is a full-stack, multi-client personal knowledge-base application (Dnote).
- It comprises:
- A server (Go) exposing a REST/JSON API, backed by SQLite/PostgreSQL migrations.
- Multiple clients:
– CLI (Go) with local storage and sync.
– Browser extension (TypeScript/React).
– Web application (TypeScript/React).
– Shared JS library (jslib) providing common helpers and service layers.
- Purpose: capture, store, sync, and review notes across devices with spaced repetition.

##### File structure
- Top-level directories:
- pkg/cli: Go CLI with local DB, commands (add, edit, sync, login, etc.).
- pkg/server: Go API server, database layer, background jobs, mailer.
- browser: Chrome/Firefox extension, UI in React/TS, uses jslib.
- web: Web client in React/TS, webpack builds.
- jslib: Shared JS/TS helpers, operations, services.
- Key config/build files:
- Makefile, Travis CI, Gopkg.{toml,lock} for Go dependencies.
- browser/package.json & webpack.config.js.
- web/webpack and package.json.
- pkg/server/.env.*, database/sql-migrate.yml.
- Architectural patterns:
- REST API layer in server/api/handlers → operations → presenters.
- CLI and clients use service modules to call HTTP endpoints.
- Shared state management per client via Redux-style stores.

##### README for additional insights
- Confirms multi-client support, local storage (SQLite), sync to server, email jobs, spaced repetition.
- Mentions self-hosting instructions (SELF_HOSTING.md).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        direction TB
        CLI["CLI Client"]:::frontend
        LocalDB["SQLite (Local DB)"]:::db
        CLI -->|"Sync (HTTPS)"| API["HTTP API"]:::backend
        CLI --> LocalDB

        BEUI["Browser Extension UI"]:::frontend
        BEBackground["Background Scripts"]:::frontend
        BEUI --> BEBackground
        BEBackground -->|"HTTPS"| API
        click BEUI "https://github.com/lolzboring/dnote/tree/master/browser/src"
        click CLI "https://github.com/lolzboring/dnote/tree/master/pkg/cli"

        WAUI["Web Application"]:::frontend
        WAUI -->|"HTTPS"| API
        click WAUI "https://github.com/lolzboring/dnote/tree/master/web/src"

        SharedLib["Shared JS Library"]:::lib
        BEBackground --> SharedLib
        WAUI --> SharedLib
        click SharedLib "https://github.com/lolzboring/dnote/tree/master/jslib/src"
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        subgraph "API Layer"
            direction TB
            Handlers["Handlers"]:::backend
            Operations["Operations"]:::backend
            Presenters["Presenters"]:::backend
            Handlers --> Operations --> Presenters
            click Handlers "https://github.com/lolzboring/dnote/tree/master/pkg/server/api/handlers"
            click Operations "https://github.com/lolzboring/dnote/tree/master/pkg/server/api/operations"
            click Presenters "https://github.com/lolzboring/dnote/blob/master/pkg/server/api/presenters/presenters.go"
        end

        API --> DBLayer["Database Layer"]:::db
        click DBLayer "https://github.com/lolzboring/dnote/tree/master/pkg/server/database"

        Migrations["Migrations Config"]:::backend
        Migrations --> DBLayer
        click Migrations "https://github.com/lolzboring/dnote/blob/master/pkg/server/database/sql-migrate.yml"

        JobProcessor["Job Processor"]:::backend
        JobProcessor -->|"reads/writes"| DBLayer
        click JobProcessor "https://github.com/lolzboring/dnote/tree/master/pkg/server/job"

        Mailer["Mailer Service"]:::backend
        JobProcessor -->|-->|Mailer
        click Mailer "https://github.com/lolzboring/dnote/tree/master/pkg/server/mailer"

        SMTP["SMTP Provider"]:::external
        Mailer -->|SMTP| SMTP

        EnvConfig["Environment Config"]:::backend
        EnvConfig --> Handlers
        EnvConfig --> JobProcessor
        EnvConfig --> Mailer
        click EnvConfig "https://github.com/lolzboring/dnote/blob/master/pkg/server/.env.dev"
        click EnvConfig "https://github.com/lolzboring/dnote/blob/master/pkg/server/.env.test"
    end

    %% Connections
    API --> Handlers
    API --> Operations
    API --> Presenters

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef lib fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef db fill:#98FB98,stroke:#333,stroke-width:1px
```
