kapitanov/moex-bond-recommender

<explanation>

1. Identify the project type and purpose

• This is a full‑stack Go application called “moex‑bond‑recommender.”

• It provides both a command‑line interface (CLI) and an HTTP/web UI.

• It fetches bond and market data from the public MOEX API, stores it in Postgres, runs background jobs, and answers recommendation, search, and viewing requests.

2. Main components

• External Systems

– MOEX Public API (iss.moex.com)

– PostgreSQL Database

• Infrastructure

– Docker / docker-compose orchestrates two containers: the Go service and Postgres

– GitHub Actions for CI/CD (go.yml)

• Application Layers (in pkg/)

1. Core App Layer (pkg/app)

• Entry point for both CLI commands and HTTP handlers

• Defines interfaces (App) and wiring (unit_of_work, BG jobs)

2. Data Layer (pkg/data)

• DB migrations, schema definitions, repositories for bonds, issuers, offers, cashflows, payments, reports, collections, search indexes

• Uses a Unit of Work pattern to group operations

3. Fetch Service (pkg/fetch)

• Periodically or on‑demand pulls raw data from MOEX, normalizes it, writes to data layer

4. MOEX Client (pkg/moex)

• Low‑level HTTP client and parsers for MOEX endpoints: market data, offers, coupons, amortizations, securities, descriptions

5. Recommender Service (pkg/recommender)

• Business logic that analyzes stored data and computes bond purchase recommendations

6. Search Module (pkg/search)

• Full‑text or attribute search over bond data

7. Web Layer (pkg/web) + Templates + Static Assets (www/, templates/)

• HTTP routes and page controllers for index, bond detail, collection pages, search, suggestions, error pages

• HTML templates and front‑end JS for interactive charts and suggestion calculators

3. Relationships and data flow

1. Fetch workflow

• Background job or CLI “fetch” command

→ calls fetch service

→ uses moex client to request MOEX API

→ normalizes data

→ writes to Postgres via data layer

2. Recommendation workflow

• User hits web endpoint or CLI “recommend”

→ web handler or CLI calls App interface

→ App orchestrates recommender service, fetching data from the data layer

→ returns results (JSON or rendered template)

3. Search workflow

• Similar to recommendation: web or CLI “search” goes through search module

4. View workflow

• Retrieves single bond or collection details via data layer

→ renders via templates or CLI output

4. Architectural patterns and principles

• Layered (ports & adapters / onion) architecture

• Separation of concerns:

– MOEX client vs. fetch vs. data persistence vs. business logic vs. web/CLI adapters

• Unit of Work to group DB operations and maintain transactional integrity

• Background jobs for periodic data ingestion

• Clear boundaries between synchronous HTTP requests and asynchronous data fetching

5. Key technologies and frameworks

• Go modules and standard library (net/http, database/sql)

• PostgreSQL

• Docker & docker‑compose

• HTML templates (Go’s text/template / html/template)

• Vanilla JS for front‑end charts and calculators

• GitHub Actions for testing and build pipeline

6. Guidelines for tailoring the diagram

• For this full‑stack service, draw two main “lanes”:

– Backend services (Go processes)

– Frontend/UI (templates + JS + browser)

• Show the separation between CLI commands and HTTP server as two entry points into the same App core

• Illustrate external dependencies (Postgres, MOEX API) as boxes outside your system

• Depict background fetch jobs as a scheduled component calling the fetch service

• Emphasize the layered flow:

– Adapters (web routes / CLI commands) → App core → Services (recommender/search/fetch) → Data layer → Database

7. Diagram elements and styling

• Use clear labels for each component (e.g., “pkg/data: Repository Layer,” “pkg/fetch: Fetch Service”)

• Draw directional arrows for data and control flow (e.g., fetch → normalize → write to DB)

• Color‑code by layer or type:

– Blue for internal application components

– Green for external dependencies (MOEX API, Postgres)

– Orange for user‑facing interfaces (browser, CLI)

• Use distinct shapes:

– Cylinders for Databases

– Clouds for external APIs

– Rectangles for services/modules

– Document icons for templates/static files

• Group related packages into bounded contexts with a lightly shaded background

Final tip: Don’t overcrowd the diagram—start by plotting major components and their relations, then drill down by detailing each layer. This ensures you capture all essential architectural elements without losing clarity.