Reference

A single-page lookup table for the stock-analysis umbrella. All paths prefixed with /api/nepse/. All endpoints public (rate-limited at 30 req/min/IP under the rl30 group), HTTP GET only.

All 9 endpoints

Per-symbol (8 endpoints, tag `Fundamentals`)

Method	Path	Handler	Cache TTL
`GET`	`/companies/{symbol}/fundamentals/snapshot`	`snapshot.Handler.HTTP`	5 min
`GET`	`/companies/{symbol}/fundamentals/statements`	`statements.Handler.HTTP`	10 min
`GET`	`/companies/{symbol}/fundamentals/ratios`	`ratios.Handler.HTTP`	10 min
`GET`	`/companies/{symbol}/fundamentals/dividends`	`dividends.Handler.HTTP`	30 min
`GET`	`/companies/{symbol}/fundamentals/ownership`	`ownership.Handler.HTTP`	1 hr
`GET`	`/companies/{symbol}/fundamentals/peers`	`peers.Handler.HTTP`	10 min
`GET`	`/companies/{symbol}/fundamentals/announcements`	`announcements.Handler.HTTP`	5 min
`GET`	`/companies/{symbol}/fundamentals/fair-value`	`fairvalue.Handler.HTTP`	10 min

Global (1 endpoint)

Method	Path	Handler	Cache TTL
`GET`	`/upcoming-book-closes`	`dividends.Handler.UpcomingBookCloses`	1 hr

Bundle composition

// internal/modules/nepse/fundamentals/stock_analysis/deps.go
type Bundle struct {
    Snapshot      *snapshot.Handler
    Statements    *statements.Handler
    Ratios        *ratios.Handler
    Dividends     *dividends.Handler
    Ownership     *ownership.Handler
    Peers         *peers.Handler
    Announcements *announcements.Handler
    FairValue     *fairvalue.Handler
}

func NewBundle(q *sqlc.Queries, tax *taxonomy.Manager, c *cache.Cache) *Bundle

Mounted from cmd/server/main.go:

stockAnalysisBundle := stockanalysis.NewBundle(queries, taxonomyManager, cacheLayer)

And from internal/http/router/router.go:

if deps.StockAnalysis != nil {
    stockanalysis.Routes(r, deps.StockAnalysis)       // 8 per-symbol
    stockanalysis.GlobalRoutes(r, deps.StockAnalysis) // /upcoming-book-closes
}

DTOs

Each feature owns its own DTO file (types.go). The cross-cutting envelope:

type Envelope<T> = { message: string; data: T };

type MetricFloat64 = {
  value?: number;
  source: 'mdp' | 'computed' | 'manual_swp';
  status: 'valid' | 'upstream_missing' | 'insufficient_history' | 'negative_input' | 'insufficient_cohort';
};

DTO	File	Used by
`snapshot.Response`	`snapshot/types.go`	`GET /snapshot`
`statements.Response`	`statements/types.go`	`GET /statements`
`ratios.Response`, `ratios.Row`, `ratios.Inputs`	`ratios/types.go`	`GET /ratios`, imported by `peers`
`dividends.Response`, `dividends.UpcomingBookClosesResponse`, `dividends.UpcomingBookCloseRow`	`dividends/types.go`	`GET /dividends`, `GET /upcoming-book-closes`
`ownership.Response`, `ownership.Tier2`, `ownership.Tier4`	`ownership/types.go`	`GET /ownership`
`peers.Response`, `peers.Company`, `peers.Row`, `peers.RadarEntry`, `peers.ExcludedPeer`	`peers/types.go`	`GET /peers`
`announcements.Response`, `announcements.Row`, `announcements.ExpandResults`	`announcements/types.go`	`GET /announcements`
`fairvalue.Response`, `fairvalue.Method`, `fairvalue.Inputs`, `fairvalue.Summary`	`fair_value/types.go`	`GET /fair-value`

Cache keys

All in the nepse:fundamentals: namespace. Constants in cachekey.go:

Const	Pattern	Used by
`PrefixSnapshot`	`nepse:fundamentals:snapshot:{SYM}`	snapshot
`PrefixStatements`	`nepse:fundamentals:statements:{SYM}:{type}:{period}:y{years}`	statements
`PrefixRatios`	`nepse:fundamentals:ratios:{SYM}:{tab}`	ratios
`PrefixDividends`	`nepse:fundamentals:dividends:{SYM}:y{years}:d{upcomingDays}`	dividends
`PrefixUpcomingBookCloses`	`nepse:fundamentals:upcoming-book-closes:d{days}:l{limit}`	dividends (global)
`PrefixOwnership`	`nepse:fundamentals:ownership:{SYM}`	ownership
`PrefixPeers`	`nepse:fundamentals:peers:{FOCAL}:{sortedPeers}`	peers
`PrefixAnnouncements`	`nepse:fundamentals:announcements:{SYM}:t{sortedTypes}:f{from}:x{to}:l{limit}`	announcements
`PrefixFairValue`	`nepse:fundamentals:fair-value:{SYM}`	fair_value

sqlc queries

Located in internal/platform/database/queries/fundamentals_*.sql (and corporate_*.sql):

Query	Used by
`GetFundamentalsSnapshotCore`	snapshot, statements, ratios, peers (404 probe), announcements (404 probe), fair_value, dividends
`GetFundamentalsSnapshotReports`	snapshot, ratios, peers, fair_value
`GetFundamentalsSnapshotDividends`	snapshot, ratios, peers
`GetFundamentalsStatementsHistory`	statements
`GetFundamentalsAuditedAnnualOverrides`	statements (annual mode)
`GetFundamentalsDividendEvents`	dividends
`GetFundamentalsRightsEvents`	dividends
`GetFundamentalsTRIndexAnchor`	dividends (TR-index series)
`GetFundamentalsUpcomingBookCloseBySymbol`	dividends (per-symbol upcoming)
`GetFundamentalsUpcomingBookClosesGlobal`	dividends (global feed)
`GetFundamentalsOwnershipCore`	ownership
`GetFundamentalsOwnershipExtendedLatest`	ownership (Tier4 override)
`GetFundamentalsAuditorLatest`	ownership
`GetFundamentalsTopShareholdersLatest`	ownership
`GetAnnouncementsDividends`	announcements
`GetAnnouncementsRights`	announcements
`GetAnnouncementsAGMs`	announcements
`GetAnnouncementsMergers`	announcements
`GetAnnouncementsResults`	announcements
`GetFundamentalsFairValueSectorCohort`	fair_value

Shared compute helpers

Reused across features — internal/modules/nepse/fundamentals/compute/:

Helper	Returns	Used by
`compute.ItemsFromReports(reports, "Balance Sheet")`	`map[string]*float64`	snapshot, ratios, peers, fair_value, statements
`compute.BookValuePerShare(reg, bsItems, outstanding, sector)`	`MetricFloat64`	snapshot, ratios, fair_value
`compute.EPSCurrent(reg, isItems, sector)`	`MetricFloat64`	snapshot, ratios, fair_value
`compute.ComputeMarketCap(core)`	`*float64`	snapshot, ratios, peers, fair_value
`compute.ComputeDividendYield(dividends, ltp)`	`MetricFloat64`	snapshot, ratios

BookValuePerShare and EPSCurrent were lifted out of snapshot/ and ratios/ in P11 of the refactor — fair_value now imports them too instead of carrying near-duplicates.

Notable file paths

File	Purpose
`internal/modules/nepse/fundamentals/stock_analysis/deps.go`	Bundle + NewBundle
`internal/modules/nepse/fundamentals/stock_analysis/routes.go`	`Routes` (per-symbol) + `GlobalRoutes`
`internal/modules/nepse/fundamentals/stock_analysis/cachekey.go`	All cache-prefix constants
`internal/modules/nepse/fundamentals/stock_analysis/internal/store/store.go`	`SnapshotReader` interface (3 shared sqlc reads)
`internal/modules/nepse/fundamentals/stock_analysis/internal/goldenjson/`	JSON-shape pin tests + cache-prefix drift detector
`internal/modules/nepse/financial_reports/taxonomy/`	`Registry.LookupValue` + canonical row vocabulary
`internal/modules/nepse/fundamentals/compute/`	Shared BVPS / EPS / market cap / yield helpers
`internal/modules/nepse/fundamentals/metric/`	`MetricFloat64` + status enum
`internal/http/router/router.go:142-149`	Route mounting block
`cmd/server/main.go:312`	Bundle construction
`docs/FUNDAMENTALS_REFACTOR_PLAN.md`	Multi-phase plan that produced this layout

Reference

On this page