# knowledgr/knowledgrconnect architecture

> Architecture diagram of the GitHub repository knowledgr/knowledgrconnect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knowledgr/knowledgrconnect
- Repository: https://github.com/knowledgr/knowledgrconnect

## Overview

1. **What this repo is**
   - SteemConnect v2 is a Node.js application that acts as an authentication and transaction-broadcasting gateway for the Steem blockchain.
   - It combines a server-side API, an OAuth2 token issuance flow, and a browser UI for users to authorize apps and sign operations.

2. **Primary runtime boundary**
   - The backend is an Express-style Node server (`app.js`, `bin/www`) exposing API and web routes.
   - The frontend is a separate React/Redux single-page app under `src/`, bundled with Webpack and served through the server’s HTML entry point (`views/index.hbs`).

3. **HTTP/API surface**
   - `routes/api.js` handles core API endpoints such as `/api/me` and `/api/broadcast`.
   - `routes/oauth2.js` implements app authorization and token issuance.
   - `routes/apps.js` covers application management flows.
   - `routes/index.js` likely serves the main UI shell and general pages.

4. **Authentication model**
   - The system uses JWT-based tokens, with two roles described in the README:
     - **user tokens** for logged-in users
     - **app tokens** for applications authorized by a user
   - Token state is stored/synced via browser local storage on the client (`src/utils/localStorage.js`) and persisted/validated server-side via the database-backed token model.

5. **Data storage**
   - PostgreSQL is the persistent store, accessed through Sequelize (`db/models`, `db/migrations`, `db/seeders`).
   - The schema centers on at least three domains:
     - **apps**: registered client applications
     - **tokens**: issued auth/application tokens
     - **metadata**: supporting configuration/reference data
   - `db/config/config.json` and the migration files indicate the schema is managed as a conventional relational persistence layer.

6. **Core business logic: blockchain operations**
   - The `helpers/operations/` directory is the domain engine for Steem transaction types.
   - Each file maps to a specific Steem operation or auth-related action such as vote, comment, transfer, delegation, escrow, follow/unfollow, custom JSON, account recovery, and profile update.
   - This layer is likely responsible for validating scopes, shaping transaction payloads, and producing human-readable previews before broadcast/signing.

7. **Broadcasting and signing flow**
   - The app’s main value is not just login, but converting an authorized user action into a valid Steem posting operation.
   - The frontend presents signing/authorization screens (`src/components/Sign`, `src/components/Accounts`, `src/components/Auth`), while the backend validates permissions and issues or uses tokens to allow broadcast.
   - The broadcaster account is configured via environment variables (`BROADCASTER_USERNAME`, `BROADCASTER_POSTING_WIF`) and is the main Steem account used to relay posting permissions.

8. **Client application structure**
   - The React app is organized by feature:
     - `Auth` for login/authorization flows
     - `Apps` for app management and previews
     - `Accounts` for account creation/recovery/revocation/permissions
     - `Sign` for operation confirmation and error/success states
     - `Docs` for documentation pages
   - Shared UI primitives live in `src/widgets/` and reusable forms in `src/components/Form/`.

9. **State management and app bootstrapping**
   - Redux is used for global state, with reducers in `src/reducers/` and actions in `src/actions/`.
   - The app bootstrap and routing are defined in `src/index.js`, `src/app.js`, `src/routes.js`, and `src/store.js`.
   - `src/wrapper.js` suggests a top-level shell that likely wires providers, localization, and routing together.

10. **Internationalization**
   - Localization is a first-class subsystem.
   - Language packs live in `src/locales/` and server/client locale helpers are in `helpers/locales.json` and `src/utils/locales.js`.
   - This means the UI and many user-facing operation descriptions are designed for multi-language deployment.

11. **Validation and security boundaries**
   - Validation helpers in `helpers/validation-utils.js` and `src/utils/validator.js` suggest strong input checking on both server and client.
   - Middleware in `helpers/middleware.js` likely centralizes auth, request checks, and route protection.
   - `helpers/logger.js` and `helpers/utils.js` provide cross-cutting support functions for safe request handling and diagnostics.

12. **Build, static assets, and deployment**
   - Webpack configs in `webpack/` bundle the client application and its styles/assets.
   - Static assets live in `public/` and include CSS, fonts, images, and generated JS output.
   - Containerization and CI are present via `Dockerfile`, `circle.yml`, and `.dockerignore`, indicating the service is intended to be deployed as a standard Node container backed by PostgreSQL.

13. **External ecosystem dependencies**
   - The repo is tightly coupled to the Steem ecosystem: user accounts, posting permissions, and blockchain operation formats are central.
   - Crowd-sourced translations are managed through Crowdin (`crowdin.yaml`), and the README references a demo app and Discord support channel, which are operational but not architectural dependencies.

14. **Diagram-friendly mental model**
   - At a high level: browser UI → Express server → auth/token/database checks → Steem operation validation/signing → blockchain broadcast.
   - PostgreSQL stores apps/tokens/metadata, while the frontend provides the authorization and signing experience over the top of the API.

Main entry points: [`routes`](https://github.com/knowledgr/knowledgrconnect/tree/master/routes) (Routes), [`src`](https://github.com/knowledgr/knowledgrconnect/tree/master/src) (React app), [`helpers/token.js`](https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/token.js) (Token service), [`db`](https://github.com/knowledgr/knowledgrconnect/tree/master/db) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["Express server<br/>node entry<br/>[app.js]"]
end

subgraph group_backend["Backend"]
  node_http["Routes"]
  node_api["API<br/>[api.js]"]
  node_oauth2["OAuth2<br/>auth flow<br/>[oauth2.js]"]
  node_appsroute["Apps route<br/>app management<br/>[apps.js]"]
  node_indexroute["Web shell<br/>page routes<br/>[index.js]"]
  node_middleware{{"Middleware<br/>request guards<br/>[middleware.js]"}}
end

subgraph group_frontend["Frontend"]
  node_ui["React app<br/>spa"]
  node_features["Feature screens<br/>ui modules"]
  node_state{{"State layer<br/>redux<br/>[store.js]"}}
end

subgraph group_data["Data"]
  node_db[("PostgreSQL<br/>sequelize store")]
  node_models["Models"]
  node_seeders["Seed data<br/>db seeders"]
end

subgraph group_domain["Domain"]
  node_tokensvc{{"Token service<br/>token logic<br/>[token.js]"}}
  node_ops["Operations<br/>steem ops"]
  node_opengine{{"Op engine<br/>operation builder<br/>[operation.js]"}}
end

subgraph group_build["Build"]
  node_bundle["Webpack<br/>build pipeline"]
end

node_server -->|"mounts"| node_http
node_http -->|"exposes"| node_api
node_http -->|"exposes"| node_oauth2
node_http -->|"exposes"| node_appsroute
node_http -->|"exposes"| node_indexroute
node_http -->|"uses"| node_middleware
node_api -->|"checks"| node_tokensvc
node_oauth2 -->|"issues"| node_tokensvc
node_oauth2 -->|"reads/writes"| node_db
node_appsroute -->|"reads/writes"| node_db
node_tokensvc -->|"backs onto"| node_models
node_models -->|"maps to"| node_db
node_seeders -->|"loads"| node_db
node_ui -->|"contains"| node_features
node_ui -->|"wires"| node_state
node_features -->|"renders"| node_ops
node_features -->|"bundled by"| node_bundle
node_opengine -->|"drives"| node_ops
node_opengine -->|"consults"| node_tokensvc
node_ui -->|"served by"| node_indexroute
node_bundle -->|"compiles"| node_ui

click node_server "https://github.com/knowledgr/knowledgrconnect/blob/master/app.js"
click node_http "https://github.com/knowledgr/knowledgrconnect/tree/master/routes"
click node_api "https://github.com/knowledgr/knowledgrconnect/blob/master/routes/api.js"
click node_oauth2 "https://github.com/knowledgr/knowledgrconnect/blob/master/routes/oauth2.js"
click node_appsroute "https://github.com/knowledgr/knowledgrconnect/blob/master/routes/apps.js"
click node_indexroute "https://github.com/knowledgr/knowledgrconnect/blob/master/routes/index.js"
click node_middleware "https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/middleware.js"
click node_tokensvc "https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/token.js"
click node_ops "https://github.com/knowledgr/knowledgrconnect/tree/master/helpers/operations"
click node_opengine "https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/operation.js"
click node_db "https://github.com/knowledgr/knowledgrconnect/tree/master/db"
click node_models "https://github.com/knowledgr/knowledgrconnect/tree/master/db/models"
click node_seeders "https://github.com/knowledgr/knowledgrconnect/tree/master/db/seeders"
click node_ui "https://github.com/knowledgr/knowledgrconnect/tree/master/src"
click node_features "https://github.com/knowledgr/knowledgrconnect/tree/master/src/components"
click node_state "https://github.com/knowledgr/knowledgrconnect/blob/master/src/store.js"
click node_bundle "https://github.com/knowledgr/knowledgrconnect/tree/master/webpack"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server toneBlue
class node_http,node_api,node_oauth2,node_appsroute,node_indexroute,node_middleware toneAmber
class node_ui,node_features,node_state toneMint
class node_db,node_models,node_seeders toneRose
class node_tokensvc,node_ops,node_opengine toneIndigo
class node_bundle toneTeal
```

## Components

### Runtime

Node server and browser app

- [Express server](https://github.com/knowledgr/knowledgrconnect/blob/master/app.js): node entry · Bootstraps the HTTP server and app lifecycle · `app.js`

### Backend

HTTP routes, auth, and server-side logic

- [Routes](https://github.com/knowledgr/knowledgrconnect/tree/master/routes): http routes · Main API, OAuth, app, and shell route handlers · `routes`
- [API](https://github.com/knowledgr/knowledgrconnect/blob/master/routes/api.js): api handlers · Core user and broadcast endpoints · `routes/api.js`
- [OAuth2](https://github.com/knowledgr/knowledgrconnect/blob/master/routes/oauth2.js): auth flow · App authorization and token issuance flow · `routes/oauth2.js`
- [Apps route](https://github.com/knowledgr/knowledgrconnect/blob/master/routes/apps.js): app management · Application management and authorization pages · `routes/apps.js`
- [Web shell](https://github.com/knowledgr/knowledgrconnect/blob/master/routes/index.js): page routes · Serves the main UI entry and general pages · `routes/index.js`
- [Middleware](https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/middleware.js): request guards · Cross-cutting auth, validation, and route protection · `helpers/middleware.js`

### Frontend

React app and shared UI

- [React app](https://github.com/knowledgr/knowledgrconnect/tree/master/src): spa · Browser client with routing, state, and feature screens · `src`
- [Feature screens](https://github.com/knowledgr/knowledgrconnect/tree/master/src/components): ui modules · Auth, apps, accounts, docs, and signing flows · `src/components`
- [State layer](https://github.com/knowledgr/knowledgrconnect/blob/master/src/store.js): redux · Application state, actions, and reducers · `src/store.js`

### Data

Persistent models and seed data

- [PostgreSQL](https://github.com/knowledgr/knowledgrconnect/tree/master/db): sequelize store · Relational persistence for apps, tokens, and metadata · `db`
- [Models](https://github.com/knowledgr/knowledgrconnect/tree/master/db/models): sequelize models · Sequelize model layer and schema bindings · `db/models`
- [Seed data](https://github.com/knowledgr/knowledgrconnect/tree/master/db/seeders): db seeders · Initial metadata and sample records · `db/seeders`

### Domain

Steem operation and token logic

- [Token service](https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/token.js): token logic · JWT token handling and server-side token state · `helpers/token.js`
- [Operations](https://github.com/knowledgr/knowledgrconnect/tree/master/helpers/operations): steem ops · Steem operation definitions, validation, and previews · `helpers/operations`
- [Op engine](https://github.com/knowledgr/knowledgrconnect/blob/master/helpers/operation.js): operation builder · Shared operation orchestration and author metadata · `helpers/operation.js`

### Build

Bundling and deployment support

- [Webpack](https://github.com/knowledgr/knowledgrconnect/tree/master/webpack): build pipeline · Client bundling and asset build configuration · `webpack`

## Connections

- Express server → Routes: mounts · The server wires route handlers into the HTTP app
- Routes → API: exposes · API route module handles blockchain and profile endpoints
- Routes → OAuth2: exposes · OAuth route module handles authorization and token issuance
- Routes → Apps route: exposes · Apps route module handles app management flows
- Routes → Web shell: exposes · Index routes serve the UI shell and general pages
- Routes → Middleware: uses · Routes rely on shared request guards and validation
- API → Token service: checks · API handlers validate auth and token scope
- OAuth2 → Token service: issues · OAuth flow creates and persists tokens
- OAuth2 → PostgreSQL: reads/writes · Authorization state is stored in the database
- Apps route → PostgreSQL: reads/writes · App metadata and authorization state are persisted
- Token service → Models: backs onto · Token service is implemented through Sequelize models
- Models → PostgreSQL: maps to · Models define the relational persistence schema
- Seed data → PostgreSQL: loads · Seeders initialize reference and sample records
- React app → Feature screens: contains · The React SPA is composed of feature screens
- React app → State layer: wires · App bootstrap connects routing and global state
- Feature screens → Operations: renders · Signing and authorization views present operation-specific flows
- Feature screens → Webpack: bundled by · Frontend source is built through the webpack pipeline
- Op engine → Operations: drives · Shared operation logic centralizes payload shaping and validation
- Op engine → Token service: consults · Operation handling depends on auth scope and token state
- React app → Web shell: served by · The SPA shell is delivered through the server-side entry page
- Webpack → React app: compiles · Webpack compiles the client application and assets