Glossary

Loading…

Glossary

Relevant source files

• .github/workflows/build-docs.yml
• Cargo.toml
• README.md
• examples/fuzzy_match_company.rs
• examples/ipo_list.rs
• examples/ipo_show.rs
• src/enums.rs
• src/enums/form_type_enum.rs
• src/enums/fundamental_concept_enum.rs
• src/enums/url_enum.rs
• src/lib.rs
• src/models/nport_investment.rs
• src/models/ticker.rs
• src/network/fetch_cik_by_ticker_symbol.rs
• src/network/fetch_company_tickers.rs
• src/network/fetch_us_gaap_fundamentals.rs
• src/network/filings/filing_index.rs
• src/network/filings/mod.rs

This glossary defines the technical terms, abbreviations, and domain-specific concepts used throughout the rust-sec-fetcher codebase. It serves as a reference for onboarding engineers to understand the intersection of SEC regulatory requirements, financial data structures, and the system’s implementation patterns.

SEC & EDGAR Terminology

The following terms originate from the U.S. Securities and Exchange Commission (SEC) and its Electronic Data Gathering, Analysis, and Retrieval (EDGAR) system.

Accession Number

A unique identifier assigned by the SEC to every filing. It follows the format 0000320193-25-000008, where the first part is the CIK of the filer, the second is the year, and the third is a sequence number.

• Code Entity: AccessionNumber src/models/mod.rs (not shown, but referenced in src/network/fetch_us_gaap_fundamentals.rs2).
• Usage: Used to construct direct URLs to filing index pages and primary documents src/network/fetch_us_gaap_fundamentals.rs:88-94

CIK (Central Index Key)

A 10-digit number used by the SEC to uniquely identify corporations and individuals who have filed disclosures.

• Code Entity: Cik src/models/ticker.rs21
• Data Flow: Resolved from tickers via fetch_cik_by_ticker_symbol src/network/fetch_cik_by_ticker_symbol.rs and used as a primary key for most API calls like CompanyFacts src/network/fetch_us_gaap_fundamentals.rs62

Filing Index

The HTML landing page for a specific filing (e.g., -index.htm). It lists all documents associated with a submission, including the primary form (10-K) and all exhibits (EX-99.1).

• Code Entity: FilingIndex src/network/filings/filing_index.rs2 fetch_filing_index src/network/filings/filing_index.rs:108-114
• Implementation: Parsed using regex to extract filenames and document types src/network/filings/filing_index.rs:23-76

US GAAP & XBRL

US GAAP (Generally Accepted Accounting Principles) is the standard framework of guidelines for financial accounting. XBRL (eXtensible Business Reporting Language) is the XML-based standard used to “tag” these financial concepts (e.g., NetIncomeLoss) in filings.

• Code Entity: FundamentalConcept src/enums/fundamental_concept_enum.rs
• Data Fetching: fetch_us_gaap_fundamentals retrieves these tags from the SEC companyfacts endpoint src/network/fetch_us_gaap_fundamentals.rs:54-58

Sources: src/network/fetch_us_gaap_fundamentals.rs:11-53 src/network/filings/filing_index.rs:14-22 src/models/ticker.rs:19-25

Codebase-Specific Concepts

Derived Instrument

Financial instruments that are not the primary common stock listing but share the same CIK, such as warrants (-WT), units (-UN), or preferred shares (-PA).

• Code Entity: TickerOrigin::DerivedInstrument src/enums.rs
• Logic: These are merged from ticker.txt and often require name backfilling from primary listings src/network/fetch_company_tickers.rs:27-35

Fuzzy Matching (Company Names)

A mechanism to resolve a human-readable company name to a Ticker and Cik using tokenization and weighted scoring.

• Code Entity: Ticker::get_by_fuzzy_matched_name src/models/ticker.rs:38-42
• Algorithm: Uses TOKEN_MATCH_THRESHOLD (0.6) and various boosts (e.g., EXACT_MATCH_BOOST) to rank candidates src/models/ticker.rs:27-33

Rendering Views

Traits and structures that define how a raw SEC HTML document is transformed into a readable format.

• Code Entity: FilingView examples/ipo_show.rs49 MarkdownView examples/ipo_show.rs49 EmbeddingTextView examples/ipo_show.rs49
• Usage: Passed to render_filing to determine the output format src/ops/mod.rs (referenced in examples/ipo_show.rs130).

Sources: src/network/fetch_company_tickers.rs:50-55 src/models/ticker.rs:43-122 examples/ipo_show.rs:92-108

System Architecture Diagrams

graph TD
    subgraph "Input Space"
        Input["User Input: 'AAPL' or 'Apple Inc'"]
end

    subgraph "Code Entity Space (src/network & src/models)"
        Client["SecClient"]
FetchTicker["fetch_company_tickers"]
FuzzyMatch["Ticker::get_by_fuzzy_matched_name"]
CikLookup["fetch_cik_by_ticker_symbol"]
end

    subgraph "Data Sources"
        JSON["company_tickers.json"]
TXT["ticker.txt"]
end

 
   Input --> Client
 
   Client --> FetchTicker
 
   FetchTicker --> JSON
 
   FetchTicker --> TXT
 
   FetchTicker --> FuzzyMatch
 
   Input --> CikLookup
 
   CikLookup --> Client

Ticker Resolution Pipeline

This diagram bridges the natural language “Ticker/Name” input to the code entities responsible for resolution.

Sources: src/network/fetch_company_tickers.rs:58-61 src/models/ticker.rs:38-42 src/network/fetch_cik_by_ticker_symbol.rs

graph LR
    subgraph "SEC EDGAR"
        Submissions["/submissions/CIK{cik}.json"]
IndexPage["-index.htm"]
DocHTML["primary_doc.htm"]
end

    subgraph "Logic (src/network/filings & src/ops)"
        FetchSub["fetch_cik_submissions"]
FetchIdx["fetch_filing_index"]
RenderOp["render_filing"]
end

    subgraph "Views (src/views)"
        MDV["MarkdownView"]
ETV["EmbeddingTextView"]
end

 
   Submissions --> FetchSub
 
   FetchSub --> FetchIdx
 
   FetchIdx --> IndexPage
 
   IndexPage --> RenderOp
 
   RenderOp --> DocHTML
 
   RenderOp --> MDV
 
   RenderOp --> ETV

Filing Retrieval and Rendering Flow

This diagram shows the transition from a raw SEC submission to a rendered view.

Sources: src/network/filings/filing_index.rs:108-114 src/network/fetch_us_gaap_fundamentals.rs:74-81 examples/ipo_show.rs:110-114

Terminology Summary Table

Sources: src/models/nport_investment.rs:11-41 src/network/filings/mod.rs:16-29 examples/ipo_list.rs:1-17 src/models/ticker.rs:13-17

Dismiss

Refresh this wiki

Enter email to refresh