# bkstar123/kstock-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/bkstar123/kstock-v2
- Repository: https://github.com/bkstar123/kstock-v2

## Overview

KStock is an admin-facing Vietnamese stock analysis platform. Admins add symbols, request quarterly or annual statements, and receive queued pulls; saved statements can be analyzed into company-type-specific ratios and viewed over rolling periods. Separate product areas cover company profiles and valuation, side-by-side comparisons, watchlists, freshness settings, and role-based administration. The graph combines sampled controller behavior with major README-documented capabilities; several feature implementations were not sampled, so their internal wiring is intentionally not expanded.

Main entry points: [`app/Jobs/AnalyzeFinancialStatement.php`](https://github.com/bkstar123/kstock-v2/blob/main/app/Jobs/AnalyzeFinancialStatement.php) (Analysis job), [`app/Http/Controllers/CompanyController.php`](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/CompanyController.php) (Company directory), [`app/Models/FinancialStatement.php`](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/FinancialStatement.php) (Financial statements), [`app/Http/Controllers/SymbolController.php`](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/SymbolController.php) (Statement controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Statement ingestion"]
  node_symbol_controller["Statement controller"]
  node_pull_job["Statement pull job"]
  node_statement_library["Statement library"]
  node_statement_store[("Financial statements")]
  node_statement_models["Statement models<br/>[BaseStatement.php]"]
end

subgraph group_analysis["Financial analysis"]
  node_analyze_job["Analysis job"]
  node_calculators["Ratio calculators"]
  node_analysis_writers["Report writers"]
  node_analysis_store[("Analysis reports<br/>[AnalysisReport.php]")]
  node_completion_events["Completion events"]
end

subgraph group_market["Market insights"]
  node_company_controller["Company directory"]
  node_symbol_services["Symbol services<br/>[Symbols.php]"]
  node_comparison["Stock comparison"]
  node_watchlist["Watchlist"]
  node_watchlist_model[("Watchlist records<br/>[Watchlist.php]")]
  node_directory_model[("Symbol directory<br/>[DirectoryEntry.php]")]
end

subgraph group_admin["Admin operations"]
  node_settings["Freshness settings"]
  node_admin_panel["Admin and RBAC<br/>[routes.php]"]
  node_authz["Access policies"]
end

subgraph group_presentation["User interface"]
  node_statements_ui["Statement screens<br/>[index.blade.php]"]
  node_company_data["Company hub views<br/>[show.blade.php]"]
  node_comparison_view["Comparison view<br/>[index.blade.php]"]
end

node_admins(("Admin user"))
node_market_api{{"Market-data API"}}
node_pusher{{"Realtime notifications"}}

node_admins -->|"requests statements"| node_statements_ui
node_statements_ui -->|"submits pull"| node_symbol_controller
node_symbol_controller -->|"attaches ownership"| node_statement_library
node_symbol_controller -->|"dispatches pull"| node_pull_job
node_pull_job -->|"fetches statements"| node_market_api
node_pull_job -->|"updates statement"| node_statement_store
node_statement_library -->|"tracks ownership"| node_statement_store
node_statement_store -->|"stores periods"| node_statement_models
node_statement_store -->|"provides saved data"| node_analyze_job
node_analyze_job -->|"computes ratios"| node_calculators
node_analyze_job -->|"writes report data"| node_analysis_writers
node_analysis_writers -->|"persists reports"| node_analysis_store
node_analyze_job -->|"emits completion"| node_completion_events
node_completion_events -.->|"broadcasts update"| node_pusher
node_admins -->|"browses companies"| node_company_controller
node_company_controller -->|"requests market data"| node_symbol_services
node_symbol_services -->|"fetches quotes and fundamentals"| node_market_api
node_company_controller -->|"manages directory"| node_directory_model
node_company_controller -->|"renders hub"| node_company_data
node_admins -->|"compares tickers"| node_comparison
node_comparison -->|"requests indicators"| node_symbol_services
node_comparison -->|"renders comparison"| node_comparison_view
node_admins -->|"manages watchlist"| node_watchlist
node_watchlist -->|"reads and writes"| node_watchlist_model
node_admins -->|"configures freshness"| node_settings
node_settings -.->|"configures credentials"| node_market_api
node_admins -->|"administers accounts"| node_admin_panel
node_admin_panel -->|"checks permissions"| node_authz

click node_statements_ui "https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/symbols/statements/index.blade.php"
click node_symbol_controller "https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/SymbolController.php"
click node_pull_job "https://github.com/bkstar123/kstock-v2/blob/main/app/Jobs/PullFinancialStatement.php"
click node_statement_library "https://github.com/bkstar123/kstock-v2/blob/main/app/Services/StatementLibrary.php"
click node_statement_store "https://github.com/bkstar123/kstock-v2/blob/main/app/Models/FinancialStatement.php"
click node_statement_models "https://github.com/bkstar123/kstock-v2/blob/main/app/Models/BaseStatement.php"
click node_analyze_job "https://github.com/bkstar123/kstock-v2/blob/main/app/Jobs/AnalyzeFinancialStatement.php"
click node_calculators "https://github.com/bkstar123/kstock-v2/tree/main/app/Jobs/Financials/Calculators"
click node_analysis_writers "https://github.com/bkstar123/kstock-v2/tree/main/app/Jobs/Financials/Writers"
click node_analysis_store "https://github.com/bkstar123/kstock-v2/blob/main/app/Models/AnalysisReport.php"
click node_completion_events "https://github.com/bkstar123/kstock-v2/blob/main/app/Events/AnalyzeFinancialStatementCompleted.php"
click node_company_controller "https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/CompanyController.php"
click node_symbol_services "https://github.com/bkstar123/kstock-v2/blob/main/app/Services/Symbols.php"
click node_company_data "https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/companies/show.blade.php"
click node_comparison "https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/ComparisonController.php"
click node_comparison_view "https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/compare/index.blade.php"
click node_watchlist "https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/WatchlistController.php"
click node_watchlist_model "https://github.com/bkstar123/kstock-v2/blob/main/app/Models/Watchlist.php"
click node_settings "https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/SettingController.php"
click node_admin_panel "https://github.com/bkstar123/kstock-v2/blob/main/packages/bkscms-admin-panel/src/routes/routes.php"
click node_authz "https://github.com/bkstar123/kstock-v2/blob/main/app/Providers/AuthServiceProvider.php"
click node_directory_model "https://github.com/bkstar123/kstock-v2/blob/main/app/Models/DirectoryEntry.php"

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_symbol_controller,node_pull_job,node_statement_library,node_statement_store,node_statement_models,node_admins toneBlue
class node_analyze_job,node_calculators,node_analysis_writers,node_analysis_store,node_completion_events toneAmber
class node_company_controller,node_symbol_services,node_comparison,node_watchlist,node_watchlist_model,node_directory_model,node_market_api toneMint
class node_settings,node_admin_panel,node_authz toneRose
class node_statements_ui,node_company_data,node_comparison_view,node_pusher toneIndigo
```

## Components

### Statement ingestion

- [Statement controller](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/SymbolController.php): `app/Http/Controllers/SymbolController.php`
- [Statement pull job](https://github.com/bkstar123/kstock-v2/blob/main/app/Jobs/PullFinancialStatement.php): `app/Jobs/PullFinancialStatement.php`
- [Statement library](https://github.com/bkstar123/kstock-v2/blob/main/app/Services/StatementLibrary.php): `app/Services/StatementLibrary.php`
- [Financial statements](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/FinancialStatement.php): `app/Models/FinancialStatement.php`
- [Statement models](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/BaseStatement.php): `app/Models/BaseStatement.php`

### Financial analysis

- [Analysis job](https://github.com/bkstar123/kstock-v2/blob/main/app/Jobs/AnalyzeFinancialStatement.php): `app/Jobs/AnalyzeFinancialStatement.php`
- [Ratio calculators](https://github.com/bkstar123/kstock-v2/tree/main/app/Jobs/Financials/Calculators): `app/Jobs/Financials/Calculators`
- [Report writers](https://github.com/bkstar123/kstock-v2/tree/main/app/Jobs/Financials/Writers): `app/Jobs/Financials/Writers`
- [Analysis reports](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/AnalysisReport.php): `app/Models/AnalysisReport.php`
- [Completion events](https://github.com/bkstar123/kstock-v2/blob/main/app/Events/AnalyzeFinancialStatementCompleted.php): `app/Events/AnalyzeFinancialStatementCompleted.php`

### Market insights

- [Company directory](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/CompanyController.php): `app/Http/Controllers/CompanyController.php`
- [Symbol services](https://github.com/bkstar123/kstock-v2/blob/main/app/Services/Symbols.php): `app/Services/Symbols.php`
- [Stock comparison](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/ComparisonController.php): `app/Http/Controllers/ComparisonController.php`
- [Watchlist](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/WatchlistController.php): `app/Http/Controllers/WatchlistController.php`
- [Watchlist records](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/Watchlist.php): `app/Models/Watchlist.php`
- [Symbol directory](https://github.com/bkstar123/kstock-v2/blob/main/app/Models/DirectoryEntry.php): `app/Models/DirectoryEntry.php`

### Admin operations

- [Freshness settings](https://github.com/bkstar123/kstock-v2/blob/main/app/Http/Controllers/SettingController.php): `app/Http/Controllers/SettingController.php`
- [Admin and RBAC](https://github.com/bkstar123/kstock-v2/blob/main/packages/bkscms-admin-panel/src/routes/routes.php): `packages/bkscms-admin-panel/src/routes/routes.php`
- [Access policies](https://github.com/bkstar123/kstock-v2/blob/main/app/Providers/AuthServiceProvider.php): `app/Providers/AuthServiceProvider.php`

### User interface

- [Statement screens](https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/symbols/statements/index.blade.php): `resources/views/cms/symbols/statements/index.blade.php`
- [Company hub views](https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/companies/show.blade.php): `resources/views/cms/companies/show.blade.php`
- [Comparison view](https://github.com/bkstar123/kstock-v2/blob/main/resources/views/cms/compare/index.blade.php): `resources/views/cms/compare/index.blade.php`

### Other components

- **Admin user**
- **Market-data API**
- **Realtime notifications**

## Connections

- Admin user → Statement screens: requests statements
- Statement screens → Statement controller: submits pull
- Statement controller → Statement library: attaches ownership
- Statement controller → Statement pull job: dispatches pull
- Statement pull job → Market-data API: fetches statements
- Statement pull job → Financial statements: updates statement
- Statement library → Financial statements: tracks ownership
- Financial statements → Statement models: stores periods
- Financial statements → Analysis job: provides saved data
- Analysis job → Ratio calculators: computes ratios
- Analysis job → Report writers: writes report data
- Report writers → Analysis reports: persists reports
- Analysis job → Completion events: emits completion
- Completion events → Realtime notifications: broadcasts update
- Admin user → Company directory: browses companies
- Company directory → Symbol services: requests market data
- Symbol services → Market-data API: fetches quotes and fundamentals
- Company directory → Symbol directory: manages directory
- Company directory → Company hub views: renders hub
- Admin user → Stock comparison: compares tickers
- Stock comparison → Symbol services: requests indicators
- Stock comparison → Comparison view: renders comparison
- Admin user → Watchlist: manages watchlist
- Watchlist → Watchlist records: reads and writes
- Admin user → Freshness settings: configures freshness
- Freshness settings → Market-data API: configures credentials
- Admin user → Admin and RBAC: administers accounts
- Admin and RBAC → Access policies: checks permissions
