How knowledgr/knowledgrconnect works
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 Routes · src React app · token.js Token service · db PostgreSQL
Components 17
Runtime
Node server and browser app
- Express server · Bootstraps the HTTP server and app lifecycle
app.js
Backend
HTTP routes, auth, and server-side logic
- Routes · Main API, OAuth, app, and shell route handlers
routes - API · Core user and broadcast endpoints
routes/api.js - OAuth2 · App authorization and token issuance flow
routes/oauth2.js - Apps route · Application management and authorization pages
routes/apps.js - Web shell · Serves the main UI entry and general pages
routes/index.js - Middleware · Cross-cutting auth, validation, and route protection
helpers/middleware.js
Frontend
React app and shared UI
- React app · Browser client with routing, state, and feature screens
src - Feature screens · Auth, apps, accounts, docs, and signing flows
src/components - State layer · Application state, actions, and reducers
src/store.js
Data
Persistent models and seed data
- PostgreSQL · Relational persistence for apps, tokens, and metadata
db - Models · Sequelize model layer and schema bindings
db/models - Seed data · Initial metadata and sample records
db/seeders
Domain
Steem operation and token logic
- Token service · JWT token handling and server-side token state
helpers/token.js - Operations · Steem operation definitions, validation, and previews
helpers/operations - Op engine · Shared operation orchestration and author metadata
helpers/operation.js
Connections 21
- 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