{"id":49618478,"url":"https://github.com/joaosantossgp/analisys","last_synced_at":"2026-06-02T20:00:32.049Z","repository":{"id":350929523,"uuid":"1208772202","full_name":"joaosantossgp/analisys","owner":"joaosantossgp","description":"Local-first Windows desktop financial data tool for Brazilian public companies, built with Python, SQLite, pywebview, and Vite.","archived":false,"fork":false,"pushed_at":"2026-06-02T00:42:45.000Z","size":58692,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T01:20:08.942Z","etag":null,"topics":["brazilian-market","cvm","data-pipeline","desktop-app","equity-research","financial-data","python","pywebview","sqlite","vite","windows"],"latest_commit_sha":null,"homepage":"https://joaosantossgp.github.io/analisys/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joaosantossgp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"docs/governance/autonomous-mode.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-12T18:14:28.000Z","updated_at":"2026-06-02T00:42:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joaosantossgp/analisys","commit_stats":null,"previous_names":["joaosantossgp/analisys"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/joaosantossgp/analisys","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaosantossgp%2Fanalisys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaosantossgp%2Fanalisys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaosantossgp%2Fanalisys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaosantossgp%2Fanalisys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joaosantossgp","download_url":"https://codeload.github.com/joaosantossgp/analisys/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaosantossgp%2Fanalisys/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazilian-market","cvm","data-pipeline","desktop-app","equity-research","financial-data","python","pywebview","sqlite","vite","windows"],"created_at":"2026-05-05T00:06:01.852Z","updated_at":"2026-06-02T20:00:32.033Z","avatar_url":"https://github.com/joaosantossgp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CVMAnalytics\n\n## Overview\n\nCVMAnalytics is a local-first Windows desktop application for collecting, organizing, and analyzing Brazilian public company financial data. The app combines a Python data pipeline, a local SQLite database, and a packaged desktop UI through pywebview.\n\nThe authoritative runtime is the packaged Windows desktop executable. The public landing page (`landing/`, published via GitHub Pages) is a marketing surface only — it is not the product. The old Vercel deploy is retired.\n\n## Download\n\n**[⬇ Download the latest Windows build (CVMAnalytics-windows.zip)](https://github.com/joaosantossgp/analisys/releases/latest/download/CVMAnalytics-windows.zip)**\n\n- Checksum: [CVMAnalytics-windows.zip.sha256](https://github.com/joaosantossgp/analisys/releases/latest/download/CVMAnalytics-windows.zip.sha256)\n- All releases: [github.com/joaosantossgp/analisys/releases](https://github.com/joaosantossgp/analisys/releases)\n\nThe download link always points to the current stable release. The link is version-stable — it does not change between releases.\n\n**Requirements**\n\n- Windows only (Windows 11, or recent Windows 10). macOS and Linux are not supported.\n- Microsoft Edge **WebView2** runtime. It is preinstalled on Windows 11 and usually present on recent Windows 10; if missing, install it from Microsoft (search \"WebView2 Runtime\").\n- The app is not code-signed yet, so Windows SmartScreen may warn on first launch. Choose **More info → Run anyway**.\n\nYour data is never written inside the install folder. The local database, Excel exports, and logs live under:\n\n```\n%USERPROFILE%\\Documents\\CVMAnalytics\\\n```\n\nUpdates and uninstalls never touch that directory.\n\n## Screenshots\n\n| Company directory | Company overview |\n|---|---|\n| ![Company directory — searchable list of B3-listed companies with sector, coverage years, and data status](docs/assets/screenshots/company-directory.png) | ![Company overview — header with CVM/B3 codes, coverage summary, and annual KPI history](docs/assets/screenshots/company-overview.png) |\n\n| Financial statements | Indicators / KPIs |\n|---|---|\n| ![Financial statements — DRE/BPA/BPP/DFC matrix with multi-year columns and Excel export](docs/assets/screenshots/financial-statements.png) | ![Indicators — KPI tape and multi-year trend charts for margins, ROE, and leverage](docs/assets/screenshots/indicators.png) |\n\n## Quick Start\n\nFor non-developers who just want to run the app:\n\n1. **Download** [CVMAnalytics-windows.zip](https://github.com/joaosantossgp/analisys/releases/latest/download/CVMAnalytics-windows.zip) (see [Download](#download) above).\n2. **Unzip** it to any folder you control, e.g. `Documents\\Apps\\CVMAnalytics`. Keep `CVMAnalytics.exe` and the `_internal\\` folder together.\n3. **Run** `CVMAnalytics.exe`. If SmartScreen warns, choose **More info → Run anyway**.\n4. **First launch** sets up a local database under `%USERPROFILE%\\Documents\\CVMAnalytics\\`. Use the in-app **Updates** screen to download CVM/B3 data for the companies you follow.\n5. **Explore**: browse the company directory, open a company for its overview, financial statements (DRE / BPA / BPP / DFC), and KPI trends, then export any company's history to Excel.\n\nThe app is local-first — your data and queries stay on your machine. New versions are picked up automatically: the app checks GitHub Releases on startup and updates in place without overwriting your data.\n\n## Who This Is For\n\n- Equity researchers and analysts who follow Brazilian publicly traded companies (CVM-regulated).\n- Developers and finance students who want a local, scriptable view of historical financial statements without a cloud account.\n- Power users who prefer keeping their data and queries on their own machine.\n\n## Key Features\n\n- Downloads and standardizes historical CVM filings (DFP / ITR) for B3-listed companies.\n- Persists everything in a local SQLite database for offline use.\n- Desktop UI with company directory, sector views, an Indicators hub for macroeconomic and sector/company KPI context, and statement matrices.\n- Excel export for any company's financial history.\n- Background refresh queue with per-company status, retries, and freshness signals.\n- Auto-updater that downloads new releases from GitHub and applies them without overwriting user data.\n\n## Current Architecture\n\n```\n┌────────────────────────────────────────────────────────────────┐\n│                      CVMAnalytics.exe                          │\n│                                                                │\n│  PyInstaller bundle:                                           │\n│    • Python core (src/)            – pipeline, DB, KPIs        │\n│    • pywebview window              – WebView2 / Edge Chromium  │\n│    • desktop/bridge.py             – window.pywebview.api      │\n│    • Vite static SPA               – only packaged UI runtime  │\n│                                                                │\n│  User-writable data lives outside the install dir:             │\n│    %USERPROFILE%\\Documents\\CVMAnalytics\\db\\cvm_financials.db   │\n└────────────────────────────────────────────────────────────────┘\n```\n\n- **Python (`src/`)** owns the data pipeline, SQLite access, KPI engine, refresh worker, and Excel export.\n- **pywebview** hosts WebView2 and exposes Python callables to JavaScript as `window.pywebview.api`.\n- **Vite + React + TypeScript** under `apps/desktop-web/` builds to a static SPA served from a local loopback HTTP server. This is the only packaged desktop UI runtime.\n- **FastAPI (`apps/api/`)** remains in source as an HTTP API/development backend adapter and API test surface. It is not started or packaged by the desktop runtime.\n\nThe Phase 3 sequence ported every P0 production screen into Vite (statements, KPIs, sectors, Excel export, refresh, status/updater). Phase 4 (`v0.14.0`) made Vite the default. Phase 5B (`v0.15.0`) removed the desktop-packaged Node runtime. The old source-only Next.js app was later removed from the active tree to avoid ambiguity. Phase 6 (`v0.17.0`) completed the final product hardening audit, standardized KPI/monospaced styling, and finalized the stable release pass. See `docs/archive/migration/` for historical detail.\n\n## Active Application Source of Truth\n\n- Active frontend: `apps/desktop-web` (Vite + React + TypeScript).\n- Active runtime integration: pywebview loads the Vite build and exposes `desktop/bridge.py` through `window.pywebview.api`.\n- Do not create or modify Next.js routes, pages, layouts, API routes, or components. The old `apps/web` Next.js app was removed.\n- Do not infer current architecture from archived, migration, release, or legacy folders. Inspect `apps/desktop-web`, `desktop/`, `src/`, and `apps/api` before changing app behavior.\n- If a file appears legacy or unused, report it instead of modifying it.\n\n## Runtime Model\n\n- Local-first. Authoritative runtime is the Windows desktop app.\n- Default runtime: the desktop app launches Python, serves the Vite SPA over a loopback HTTP server, and loads it inside the pywebview window. No bundled Node process is spawned.\n- `--legacy` is no longer supported in the packaged app. It shows a short warning and continues into the Vite UI.\n- All desktop data calls go through `window.pywebview.api` directly to Python — no HTTP roundtrip to a separate backend.\n\n### Launch Modes\n\n```\nCVMAnalytics.exe              Vite default (no Node process)\nCVMAnalytics.exe --vite       alias of default Vite mode\nCVMAnalytics.exe --legacy     unsupported; warns, then continues into Vite\nCVMAnalytics.exe --dev        packaged build ignores dev flag; source mode uses Vite dev server\nCVMAnalytics.exe --debug      open DevTools in the active mode\nCVMAnalytics.exe --diagnose-runtime   write diagnostics log and exit\n```\n\n## User Data Location\n\nActive runtime data root (Phase 3C and later):\n\n```\n%USERPROFILE%\\Documents\\CVMAnalytics\\\n  db\\\n    cvm_financials.db            ← active runtime database\n  output\\                        ← Excel exports\n  logs\\                          ← refresh / app logs\n  cache\\\n  backup\\                        ← legacy DB snapshots from migration\n  recovery.log\n```\n\nResolution priority for the active root:\n\n1. `CVMANALYTICS_DATA_DIR` environment variable (operator override).\n2. `%USERPROFILE%\\Documents\\CVMAnalytics` (Phase 3C default).\n3. `%LOCALAPPDATA%\\CVMAnalytics` (pre-Phase-3C fallback if `USERPROFILE`\n   is unset, e.g. service accounts).\n\nUpdater-internal staging is kept separately under\n`%LOCALAPPDATA%\\CVMAnalytics\\` (`versions/`, `update_rollback/`). These\npaths are deny-listed by the updater allowlist and are unrelated to the\nruntime data root above.\n\nLegacy migration: on first launch under v0.7.0+, if the Documents data\nroot has no database, the app does a WAL-safe `sqlite3 .backup` copy\nfrom the first existing legacy source (LocalAppData, then install-dir).\nLegacy originals are never moved or deleted, and Documents DB is never\noverwritten if it already exists.\n\nUser data is never written under the install directory. The updater can never overwrite these paths.\n\n## Development Setup\n\n```bash\n# Python deps\npip install -r requirements.txt\npip install -r apps/api/requirements-dev.txt\n\n# Vite desktop UI deps (only needed when running/building the dev UI)\ncd apps/desktop-web \u0026\u0026 npm install \u0026\u0026 cd ../..\n\n# Initialize the dev DB (repo-relative path used in dev mode)\npython scripts/setup/setup_db.py\npython scripts/setup/setup_companies_table.py\n\n# Validate environment\npython scripts/diagnostics/runtime_doctor.py --require-canonical\n\n# Run the desktop app in dev mode against the Vite dev server\npython -m desktop.app --dev\n```\n\nDev-mode database lives at `data/db/cvm_financials.db` (repo-relative). The Documents data-root contract only applies to the packaged executable.\n\nHeadless and HTTP alternatives:\n\n```bash\n# CLI refresh for a single company\npython main.py --companies PETROBRAS --start_year 2021 --end_year 2025\n\n# Optional local FastAPI\nuvicorn apps.api.app.main:app --reload\n# → Swagger at http://127.0.0.1:8000/docs\n\n# Vite UI dev server only\ncd apps/desktop-web \u0026\u0026 npm run dev\n```\n\n## Desktop Build\n\n```powershell\n# From the repo root\n.\\desktop\\build_desktop.ps1\n\n# Or, after a successful prior Vite build:\n.\\desktop\\build_desktop.ps1 -SkipViteBuild\n\n# Result\n.\\dist\\CVMAnalytics\\CVMAnalytics.exe\n```\n\nThe build script:\n\n1. Runs the Vite build in `apps/desktop-web/`.\n2. Injects the version into `desktop/__version__.py`.\n3. Runs `pyinstaller desktop/app.spec` to produce `dist/CVMAnalytics/`.\n\nThe packaged folder contains only `CVMAnalytics.exe` and `_internal/`. No user data and no dev database are bundled.\n\n## Update Flow\n\n- The app polls GitHub Releases on startup.\n- A newer tag triggers an in-app prompt.\n- The updater downloads `CVMAnalytics-windows-v\u003cversion\u003e.zip` (and its `.sha256`) into `%LOCALAPPDATA%\\CVMAnalytics\\versions\\\u003cversion\u003e\\`, validates the checksum, and extracts.\n- `desktop/update_helper.ps1` swaps only allowlisted entries (`CVMAnalytics.exe` and `_internal\\`) over the current install. A pre-swap snapshot is written to `%LOCALAPPDATA%\\CVMAnalytics\\update_rollback\\\u003cutc-ts\u003e\\`.\n- The helper never touches `data\\`, `output\\`, `logs\\`, `cache\\`, or any `*.db` / `*.db-wal` / `*.db-shm` under the install directory.\n\n## Migration Status\n\nThe desktop runtime migration is complete as of v0.17.0. All phases are released. The table below is **historical reference only** — it stops at the migration milestones and does not track the current version (see `desktop/__version__.py`).\n\n| Phase | Goal | Status |\n|---|---|---|\n| Phase 0 | User-data safety net | **Released** |\n| Phase 1 | Parallel Vite SPA shell | Done |\n| Phase 2 | Wire Vite SPA into pywebview | **Released as opt-in `--vite` (`v0.4.0`)** |\n| Phase 3A–3I | Incremental Vite parity slices | **Released through `v0.13.0`**: statements, Update Base, Documents data root, KPIs, KPI charts, sectors, sub-sector detail, Excel export (full + per-statement), single-company refresh, status/diagnostics, software updater UI |\n| Phase 3J | Default switch readiness audit | Done |\n| Phase 4 | Vite default + legacy fallback (`--legacy`) | **Released as `v0.14.0`, hotfix `v0.14.1`.** Default startup loads the Vite SPA with no Node process. |\n| Phase 5A | Legacy deletion audit | Done. Confirmed `apps/desktop-web` was the desktop UI and the old web app was not a package dependency. |\n| Phase 5B | Remove desktop-packaged Node runtime | **Released as `v0.15.0`.** The desktop package no longer ships a bundled Node runtime or standalone web server. |\n| Phase 5C | Legacy source cleanup | Done. The old Next.js app was removed from the active tree; active scripts and docs now point at `apps/desktop-web`. |\n| Phase 6 | Stable Release / Final Product Pass | **Released (v0.17.0)** |\n\nSee:\n\n- [docs/archive/migration/README.md](docs/archive/migration/README.md) — phase tracker\n- [docs/archive/migration/PHASE_0_USER_DATA_SAFETY.md](docs/archive/migration/PHASE_0_USER_DATA_SAFETY.md) — Phase 0 spec and validation\n- [docs/archive/migration/NEXT_AGENT_HANDOFF.md](docs/archive/migration/NEXT_AGENT_HANDOFF.md) — detailed phase history (historical; migration complete as of v0.17.0)\n\n## Repository Structure\n\n```\ndesktop/          pywebview shell, PyInstaller spec, updater, build script\napps/desktop-web/ Vite static SPA packaged into the .exe  ← only packaged UI\napps/api/         HTTP API/development backend adapter + API tests, not desktop UI\nsrc/              Python core: scraper, KPI engine, refresh/read services\nmain.py           CLI entry point for headless refresh\nscripts/          Setup, batches, diagnostics, validation helpers\nlanding/          Marketing landing page\ndata/             Dev-mode SQLite DB + raw inputs (gitignored)\ndocs/             Active documentation, migration docs, ADRs\ntests/            pytest suite\nconfig/           canonical_accounts.csv — CVM account mapping (referenced by src/)\n```\n\nSee [docs/reference/repository-map.md](docs/reference/repository-map.md) for a full folder, workflow, and documentation status map.\n\nKey docs: [docs/COMO_RODAR.md](docs/COMO_RODAR.md) (run guide) · [docs/DESIGN.md](docs/DESIGN.md) (design system) · [docs/PRODUCT.md](docs/PRODUCT.md) (product brief).\n\n## Contributor Orientation\n\n**\"I want to change the desktop UI\"** → `apps/desktop-web/src/`. Read `docs/skills/CVMANALYTICS_VITE_UI_SKILL.md` first. Run `python -m desktop.app --dev` to see changes live. Components call Python exclusively through `lib/bridge/adapter.ts` — never call `window.pywebview.api` directly.\n\n**\"I want to change data or financial logic\"** → `src/`. The Python core owns the pipeline, KPI engine, DB access, refresh worker, and Excel export. Read `docs/CONTEXT.md` before touching financial calculations or column conventions.\n\n**\"I want to change packaging or the updater\"** → `desktop/`. The PyInstaller spec is `desktop/app.spec`. Build script is `desktop/build_desktop.ps1`. Auto-updater is `desktop/updater.py` + `desktop/update_helper.ps1`. Do not change these without re-running the full release pipeline — a wrong path in the spec produces a broken EXE with no obvious build-time error.\n\n**\"I want to change the HTTP API\"** → `apps/api/` (FastAPI) and shared read logic in `src/`. The API is not the desktop UI and does not affect pywebview routing unless a bridge/API contract also changes. Read `docs/reference/v2-api-contract.md` before modifying any API contract.\n\n**\"Which docs are current vs historical?\"** → `docs/active-project-map.md` and `docs/reference/repository-map.md` for the active map. Short answer: `docs/reference/` and `docs/decisions/` are active only when they do not conflict with the active Vite desktop map. `docs/archive/migration/` is completed history.\n\n**What not to touch casually:**\n- `desktop/app.spec` — PyInstaller spec; a wrong entry produces a broken EXE\n- `desktop/build_desktop.ps1` — build pipeline; test end-to-end before merging\n- `.github/workflows/release-desktop.yml` — changes affect artifacts downloaded by real users\n- `src/settings.py` — user data paths; wrong changes break the live DB location\n- `config/canonical_accounts.csv` — referenced by `src/settings.py` and 8+ scripts; moving requires coordinated multi-file update\n\n## Roadmap\n\n- Known deferred items: code signing (SmartScreen warning on download), AV/UPX review.\n\n## Known Limitations\n\n- Windows-only. macOS and Linux are not supported targets.\n- Requires Microsoft Edge WebView2 runtime (preinstalled on Windows 11; usually present on recent Windows 10).\n- The packaged desktop app is Vite-only and does not spawn a Node.js child process. `CVMAnalytics.exe --legacy` is unsupported and continues into Vite after a warning.\n- The dev database under `data/db/cvm_financials.db` is for developer use only. End users do not need it; the packaged app provisions its own DB under `%USERPROFILE%\\Documents\\CVMAnalytics` (with WAL-safe migration from legacy `%LOCALAPPDATA%` if present).\n- No telemetry. No crash reporting service is wired into the local desktop app.\n\n## License\n\nSee repository LICENSE file if present. Otherwise treat as all-rights-reserved by the author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaosantossgp%2Fanalisys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoaosantossgp%2Fanalisys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaosantossgp%2Fanalisys/lists"}