# asapino308/filinglens architecture

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

- Interactive diagram: https://gitdiagram.com/asapino308/filinglens
- Repository: https://github.com/asapino308/filinglens

## Overview

FilingLens is a local-first SEC research app. The main workflow runs from a user’s ticker search through SEC company and filing data, deterministic financial analysis, and a desktop research view; filing text can also be retrieved locally and passed with verified metrics to an optional language model for grounded answers or analyst briefs. The Streamlit app remains a fallback. The README documents these capabilities, but sampled excerpts do not show every desktop route, so uncertain internal call links are omitted.

Main entry points: [`src/filinglens/desktop/service.py`](https://github.com/asapino308/filinglens/blob/main/src/filinglens/desktop/service.py) (Research service), [`src/filinglens/sec/client.py`](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/client.py) (SEC client and cache), [`desktop/src/App.tsx`](https://github.com/asapino308/filinglens/blob/main/desktop/src/App.tsx) (Desktop workspace), [`src/filinglens/sec/composition.py`](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/composition.py) (Financial composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Research interfaces"]
  node_desktop_ui["Desktop workspace<br/>[App.tsx]"]
  node_desktop_api["Desktop API<br/>[api.py]"]
  node_research_service["Research service<br/>[service.py]"]
  node_streamlit_ui["Streamlit fallback<br/>[app.py]"]
  node_research_preferences[("Saved research")]
end

subgraph group_sec_data["SEC data"]
  node_sec_edgar{{"SEC EDGAR"}}
  node_sec_client[("SEC client and cache<br/>[client.py]")]
  node_company_lookup["Company lookup<br/>[companies.py]"]
  node_filing_data["Submissions and filings<br/>[submissions.py]"]
  node_xbrl_data["Company facts and XBRL<br/>[xbrl.py]"]
  node_financial_composition["Financial composition<br/>[composition.py]"]
end

subgraph group_analysis["Analysis and retrieval"]
  node_analytics["Statements and ratios<br/>[statements.py]"]
  node_trends_anomalies["Trends and anomalies<br/>[anomalies.py]"]
  node_filing_parser["Filing text parser<br/>[parser.py]"]
  node_filing_sections["Sections and chunks<br/>[sections.py]"]
  node_retrieval["Local retrieval<br/>[retrieval.py]"]
end

subgraph group_language["Grounded language"]
  node_grounded_qa["Grounded Q&amp;A<br/>[grounded_qa.py]"]
  node_analyst_brief["Analyst brief<br/>[analyst_brief.py]"]
  node_llm_provider["Provider adapters<br/>[base.py]"]
  node_ai_services{{"Optional AI services"}}
  node_report_export["Brief export<br/>[export.py]"]
end

node_user(("Researcher"))

node_user -->|"researches in"| node_desktop_ui
node_user -.->|"uses fallback"| node_streamlit_ui
node_desktop_ui -->|"requests data"| node_desktop_api
node_desktop_api -->|"dispatches"| node_research_service
node_desktop_ui -->|"reads and saves"| node_research_preferences
node_research_service -->|"searches companies"| node_company_lookup
node_research_service -->|"loads submissions"| node_filing_data
node_research_service -->|"loads facts"| node_xbrl_data
node_research_service -->|"composes metrics"| node_financial_composition
node_company_lookup -->|"requests directory"| node_sec_client
node_filing_data -->|"requests filings"| node_sec_client
node_xbrl_data -->|"requests company facts"| node_sec_client
node_financial_composition -->|"loads filing data"| node_sec_client
node_sec_client -->|"fetches official data"| node_sec_edgar
node_financial_composition -->|"supplies financials"| node_analytics
node_analytics -->|"screens movements"| node_trends_anomalies
node_research_service -->|"parses filing text"| node_filing_parser
node_filing_parser -->|"provides text"| node_filing_sections
node_filing_sections -->|"provides chunks"| node_retrieval
node_research_service -->|"searches evidence"| node_retrieval
node_research_service -->|"requests answers"| node_grounded_qa
node_research_service -->|"requests briefs"| node_analyst_brief
node_grounded_qa -->|"generates grounded answers"| node_llm_provider
node_analyst_brief -->|"generates brief text"| node_llm_provider
node_llm_provider -.->|"sends prompts"| node_ai_services
node_analyst_brief -->|"exports brief"| node_report_export

click node_desktop_ui "https://github.com/asapino308/filinglens/blob/main/desktop/src/App.tsx"
click node_desktop_api "https://github.com/asapino308/filinglens/blob/main/src/filinglens/desktop/api.py"
click node_research_service "https://github.com/asapino308/filinglens/blob/main/src/filinglens/desktop/service.py"
click node_streamlit_ui "https://github.com/asapino308/filinglens/blob/main/app.py"
click node_research_preferences "https://github.com/asapino308/filinglens/blob/main/desktop/src/researchPreferences.ts"
click node_sec_client "https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/client.py"
click node_company_lookup "https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/companies.py"
click node_filing_data "https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/submissions.py"
click node_xbrl_data "https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/xbrl.py"
click node_financial_composition "https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/composition.py"
click node_analytics "https://github.com/asapino308/filinglens/blob/main/src/filinglens/analytics/statements.py"
click node_trends_anomalies "https://github.com/asapino308/filinglens/blob/main/src/filinglens/analytics/anomalies.py"
click node_filing_parser "https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/parser.py"
click node_filing_sections "https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/sections.py"
click node_retrieval "https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/retrieval.py"
click node_grounded_qa "https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/grounded_qa.py"
click node_analyst_brief "https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/analyst_brief.py"
click node_llm_provider "https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/base.py"
click node_report_export "https://github.com/asapino308/filinglens/blob/main/src/filinglens/reporting/export.py"

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_desktop_ui,node_desktop_api,node_research_service,node_streamlit_ui,node_research_preferences toneBlue
class node_sec_edgar,node_sec_client,node_company_lookup,node_filing_data,node_xbrl_data,node_financial_composition toneAmber
class node_analytics,node_trends_anomalies,node_filing_parser,node_filing_sections,node_retrieval toneMint
class node_grounded_qa,node_analyst_brief,node_llm_provider,node_ai_services,node_report_export toneRose
class node_user toneIndigo
```

## Components

### Research interfaces

- [Desktop workspace](https://github.com/asapino308/filinglens/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Desktop API](https://github.com/asapino308/filinglens/blob/main/src/filinglens/desktop/api.py): `src/filinglens/desktop/api.py`
- [Research service](https://github.com/asapino308/filinglens/blob/main/src/filinglens/desktop/service.py): `src/filinglens/desktop/service.py`
- [Streamlit fallback](https://github.com/asapino308/filinglens/blob/main/app.py): `app.py`
- [Saved research](https://github.com/asapino308/filinglens/blob/main/desktop/src/researchPreferences.ts): `desktop/src/researchPreferences.ts`

### SEC data

- **SEC EDGAR**
- [SEC client and cache](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/client.py): `src/filinglens/sec/client.py`
- [Company lookup](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/companies.py): `src/filinglens/sec/companies.py`
- [Submissions and filings](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/submissions.py): `src/filinglens/sec/submissions.py`
- [Company facts and XBRL](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/xbrl.py): `src/filinglens/sec/xbrl.py`
- [Financial composition](https://github.com/asapino308/filinglens/blob/main/src/filinglens/sec/composition.py): `src/filinglens/sec/composition.py`

### Analysis and retrieval

- [Statements and ratios](https://github.com/asapino308/filinglens/blob/main/src/filinglens/analytics/statements.py): `src/filinglens/analytics/statements.py`
- [Trends and anomalies](https://github.com/asapino308/filinglens/blob/main/src/filinglens/analytics/anomalies.py): `src/filinglens/analytics/anomalies.py`
- [Filing text parser](https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/parser.py): `src/filinglens/documents/parser.py`
- [Sections and chunks](https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/sections.py): `src/filinglens/documents/sections.py`
- [Local retrieval](https://github.com/asapino308/filinglens/blob/main/src/filinglens/documents/retrieval.py): `src/filinglens/documents/retrieval.py`

### Grounded language

- [Grounded Q&A](https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/grounded_qa.py): `src/filinglens/llm/grounded_qa.py`
- [Analyst brief](https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/analyst_brief.py): `src/filinglens/llm/analyst_brief.py`
- [Provider adapters](https://github.com/asapino308/filinglens/blob/main/src/filinglens/llm/base.py): `src/filinglens/llm/base.py`
- **Optional AI services**
- [Brief export](https://github.com/asapino308/filinglens/blob/main/src/filinglens/reporting/export.py): `src/filinglens/reporting/export.py`

### Other components

- **Researcher**

## Connections

- Researcher → Desktop workspace: researches in
- Researcher → Streamlit fallback: uses fallback
- Desktop workspace → Desktop API: requests data
- Desktop API → Research service: dispatches
- Desktop workspace → Saved research: reads and saves
- Research service → Company lookup: searches companies
- Research service → Submissions and filings: loads submissions
- Research service → Company facts and XBRL: loads facts
- Research service → Financial composition: composes metrics
- Company lookup → SEC client and cache: requests directory
- Submissions and filings → SEC client and cache: requests filings
- Company facts and XBRL → SEC client and cache: requests company facts
- Financial composition → SEC client and cache: loads filing data
- SEC client and cache → SEC EDGAR: fetches official data
- Financial composition → Statements and ratios: supplies financials
- Statements and ratios → Trends and anomalies: screens movements
- Research service → Filing text parser: parses filing text
- Filing text parser → Sections and chunks: provides text
- Sections and chunks → Local retrieval: provides chunks
- Research service → Local retrieval: searches evidence
- Research service → Grounded Q&A: requests answers
- Research service → Analyst brief: requests briefs
- Grounded Q&A → Provider adapters: generates grounded answers
- Analyst brief → Provider adapters: generates brief text
- Provider adapters → Optional AI services: sends prompts
- Analyst brief → Brief export: exports brief