Contributing to Fincept Terminal

Fincept Terminal is an open-source native C++20/Qt6 financial intelligence platform with 50+ screens, embedded Python analytics, and 100+ data connectors. This guide is the canonical how-to for contributors — build, architecture, conventions.

Before you open a PR, also read the contribution policy: .github/CONTRIBUTING.md. Policy defines which PRs are accepted (linked approved issue, minimum scope, no auto-formatter churn, etc.); this file covers how to build and where code lives.

Ways to Contribute
Tech Stack
Prerequisites
Build
Run
Project Architecture
Code Conventions
Development Workflow
Language-Specific Guides
Getting Help

Ways to Contribute

Area	Examples
C++ / Qt	New screens, services, core infrastructure, performance fixes
Python	Analytics scripts, AI agents, data fetchers
Data sources	Broker integrations, government / market data connectors
Documentation	Fix broken/outdated docs (see policy for scope)
Testing	Reproduce bugs, review PRs, write tests

Tech Stack

Layer	Technology
Language	C++20 — MSVC 19.38 (VS 2022 17.8) / GCC 12.3 / Apple Clang 15.0
UI	Qt 6.8.3 EXACT Widgets (pinned)
Charts	Qt6 Charts
Networking	Qt6 Network + Qt6 WebSockets
Database	Qt6 Sql (SQLite)
Analytics	Embedded Python 3.11.9 (4000+ scripts)
Excel I/O	QXlsx v1.4.9 (FetchContent, pinned commit)
Mapping	QGeoView (pinned commit)
Build	CMake 3.27.7 + Ninja 1.11.1 (pinned, unity build)

Prerequisites

Pinned toolchain versions — enforced by CMake. Mismatch produces a clear fail-fast error.

Tool	Version
C++ compiler	MSVC 19.38 (VS 2022 17.8) / GCC 12.3 / Apple Clang 15.0 (Xcode 15.2)
CMake	3.27.7 — cmake.org
Ninja	1.11.1 — releases
Qt	6.8.3 — Qt Online Installer
Python	3.11.9 — python.org
Git	latest — git-scm.com

Optional (speeds up rebuilds): ccache 4.13.4 on Windows is auto-detected.

Build

Fastest — automated setup script

git clone https://github.com/Fincept-Corporation/FinceptTerminal.git
cd FinceptTerminal
./setup.sh      # Linux / macOS — installs toolchain + Qt via aqtinstall, then builds
setup.bat       # Windows — run from a VS 2022 Developer Command Prompt

Manual — CMake presets

All day-to-day development uses presets from fincept-qt/CMakePresets.json.

cd fincept-qt

# Configure (one-time, or after CMakeLists.txt changes)
cmake --preset win-release        # Windows
cmake --preset linux-release      # Linux
cmake --preset macos-release      # macOS

# Build (run after every code change — incremental)
cmake --build --preset win-release        # Windows
cmake --build --preset linux-release      # Linux
cmake --build --preset macos-release      # macOS

Debug builds: replace release with debug in both commands.

Manual configure if presets can't resolve Qt:

cmake -B build/win-release -G Ninja -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_PREFIX_PATH="C:/Qt/6.8.3/msvc2022_64"
cmake --build build/win-release

Run

.\build\win-release\FinceptTerminal.exe                                           # Windows
./build/linux-release/FinceptTerminal                                             # Linux
./build/macos-release/FinceptTerminal.app/Contents/MacOS/FinceptTerminal          # macOS

Project Architecture

Repository layout

finceptTerminal/
├── fincept-qt/                 # Main C++ application (all development happens here)
│   ├── src/                    # C++ source
│   ├── scripts/                # Embedded Python analytics (4000+ files)
│   ├── resources/              # Icons, assets, Qt resources
│   ├── CMakeLists.txt
│   ├── CMakePresets.json
│   ├── CLAUDE.md               # Performance/architecture rules (P1–P15, D1–D5)
│   └── DESIGN_SYSTEM.md        # Obsidian UI/UX spec
├── docs/                       # Repo-wide documentation (this file lives here)
├── .github/                    # Issue/PR templates, workflows, contribution policy
└── README.md

C++ source layout (`fincept-qt/src/`)

src/
├── app/              # Entry point, MainWindow, routing, splash
├── core/             # Config, events, logging, Result<T>, session
├── ui/               # Theme, reusable widgets, tables, charts, navigation
├── network/          # http/ and websocket/ clients
├── storage/          # SQLite, cache, secure storage, 16 repositories
├── auth/             # Guest + registered auth, JWT
├── python/           # Embedded Python bridge, PythonRunner
├── datahub/          # DataHub producers/consumers (see DATAHUB_ARCHITECTURE.md)
├── services/         # 18 service domains — market data, news, agents, workflow, etc.
├── trading/          # Trading core + 18 broker integrations
├── mcp/              # Model Context Protocol infrastructure (24 tool modules)
├── ai_chat/          # AI chat UI + LlmService
└── screens/          # 50+ terminal screens, one subdirectory each

Python scripts (`fincept-qt/scripts/`)

scripts/
├── Analytics/        # CFA-level quant modules — equity, portfolio, derivatives,
│                     #   fixed income, economics, corporate finance
├── agents/           # AI agent frameworks (finagent_core, Geopolitics, HedgeFund, …)
├── ai_quant_lab/     # ML, factor discovery, HFT, RL trading, vision quant
├── agno_trading/     # Agno-based trading agents
└── *.py              # 100+ top-level data fetchers (market, gov, economic, alt)

See fincept-qt/CLAUDE.md for the detailed service catalog and architecture rules.

Code Conventions

C++

Standard: C++20
Naming: snake_case functions/variables, PascalCase types/classes
Namespaces: namespace fincept {}, namespace fincept::ui {}; never using namespace std;
Qt: Q_OBJECT in all QObject subclasses; pointer-to-member signal/slot syntax only (never SIGNAL()/SLOT() string macros)
Error handling: Result<T> — no raw exception-based APIs across module boundaries
Logging: LOG_INFO / LOG_WARN / LOG_ERROR / LOG_DEBUG with a context tag, e.g. LOG_INFO("MarketData", "Fetched 12 quotes"). Never log API keys or credentials.

Python

Style: match surrounding code. Do not run Black / autopep8 / isort on existing files.
Logging: use the logging module (logger = logging.getLogger(__name__), logger.info(...)), never print(). Scripts run inside an embedded Qt runtime; print() output never reaches the user.
Entry points: C++ invokes scripts through PythonRunner::instance().run(...) — your script receives a JSON payload on stdin and must return JSON on stdout. See existing scripts in scripts/ for the pattern.

UI / design

Follow fincept-qt/DESIGN_SYSTEM.md (Obsidian design system). Do not introduce ad-hoc color values, typography, or spacing — use the tokens.

Mandatory architecture rules (summary)

Full detail in fincept-qt/CLAUDE.md. These are non-negotiable — PRs that violate them will be sent back:

P1. Never block the UI thread — no waitForFinished() on main thread.
P2. Lazy screen construction — use register_factory() for any screen that fetches data.
P3. Timers must start/stop in showEvent() / hideEvent(), never in constructors.
P4. Python subprocesses go through PythonRunner (max 3 concurrent).
P6. Screens render UI only; services do all fetching, caching, processing.
P14. Logs use the LOG_* macros (C++) or logger (Python). Never printf / print / std::cout.
D1–D5. Streaming data flows through the DataHub — never spawn Python directly from a screen. See fincept-qt/DATAHUB_ARCHITECTURE.md.

Development Workflow

Branch naming

feat/add-options-screen
fix/chart-render-crash
docs/update-python-guide
perf/market-data-coalesce
refactor/broker-http

Never PR from your fork's main — always a topic branch.

Commit style

type: short imperative subject line

Optional body explaining why, not what. Wrap at ~72 cols.

Types: feat, fix, docs, refactor, test, chore, perf

Before you open a PR

Confirm the issue you're fixing carries one of: good-first-issue, help-wanted, scope:approved (see .github/CONTRIBUTING.md).
Build locally and run the app — verify the fix / feature works end-to-end.
Keep the diff minimal. No auto-formatter churn.
Fill out the PR template honestly; don't tick boxes you didn't verify.

Review process, scope gate, and close-on-sight list are in .github/CONTRIBUTING.md.

Language-Specific Guides

Guide	Coverage
C++ Guide	Screens, services, core infrastructure, widgets, Qt patterns
Python Guide	Analytics modules, data fetchers, AI agents, PythonRunner contract
Architecture	System design, module boundaries, data flow

Getting Help

Channel	Link
Issues	GitHub Issues
Discussions	GitHub Discussions
Discord	discord.gg/ae87a8ygbN
Email	support@fincept.in

Good first issues carry the good-first-issue label — those are the right starting point for new contributors.

Repository: https://github.com/Fincept-Corporation/FinceptTerminal License: AGPL-3.0-or-later

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Fincept Terminal

Contents

Ways to Contribute

Tech Stack

Prerequisites

Build

Fastest — automated setup script

Manual — CMake presets

Run

Project Architecture

Repository layout

C++ source layout (`fincept-qt/src/`)

Python scripts (`fincept-qt/scripts/`)

Code Conventions

C++

Python

UI / design

Mandatory architecture rules (summary)

Development Workflow

Branch naming

Commit style

Before you open a PR

Language-Specific Guides

Getting Help

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Fincept Terminal

Contents

Ways to Contribute

Tech Stack

Prerequisites

Build

Fastest — automated setup script

Manual — CMake presets

Run

Project Architecture

Repository layout

C++ source layout (fincept-qt/src/)

Python scripts (fincept-qt/scripts/)

Code Conventions

C++

Python

UI / design

Mandatory architecture rules (summary)

Development Workflow

Branch naming

Commit style

Before you open a PR

Language-Specific Guides

Getting Help

C++ source layout (`fincept-qt/src/`)

Python scripts (`fincept-qt/scripts/`)