Skip to content

Last Updated: 2026-05-04 Owner: Docs-Dev Summary: Recommended repository structure for keeping QuantMatrix clean as it grows across UI applications, APIs, backend processes, shared code, infrastructure, and documentation.

QuantMatrix Repository Structure Guide

This document explains how the QuantMatrix repository should be organized as it grows beyond documentation into multiple runtime projects.

Use it when you want to: - understand where each kind of project belongs - keep UI, API, and backend process work separated cleanly - avoid documentation files spreading into unrelated parts of the repo - make future check-ins and onboarding much simpler

1. Repository Goal

QuantMatrix is not a documentation-only repository.

It is expected to hold multiple project types: - UI applications - backend APIs - backend worker and process services - shared contracts and utilities - infrastructure assets - documentation

The repository should therefore read like a small platform monorepo, not like a single Python package with docs attached.

applications/                 user-facing applications
  ui/                         primary operator UI or web dashboard

services/                     runtime services and backend processes
  apis/                       HTTP or WebSocket APIs
  processes/                  workers, schedulers, scanners, execution services

shared/                       reusable code shared across projects
  contracts/                  request, response, event, and schema contracts
  libraries/                  common helpers, utilities, and client packages

infrastructure/               environment and deployment assets
  local/                      local runtime assets such as compose and dev helpers
  deploy/                     deployment templates, cloud setup, and release infra

documentation/                all documentation-platform assets
  docs/                       Markdown source of truth
  portal/                     legacy static portal during transition
  tools/                      docs catalog and portal generators
  site/                       generated MkDocs build output
  mkdocs.yml                  MkDocs configuration
  requirements-docs.txt       docs-only dependency file

trading_system/               current implementation codebase (temporary legacy location)
tests/                        automated tests for the current implementation
migrations/                   current database migrations

3. What Goes Where

applications/

Put user-facing applications here.

Examples: - the main trading dashboard - an internal admin console - a strategy review UI - a mobile or tablet operator client later, if needed

Current recommendation: - keep the primary front-end application in applications/ui/

services/apis/

Put network-facing backend services here.

Examples: - FastAPI runtime API - account summary API - analytics API - settings API - internal API gateway

This is the best home for code that mainly exposes endpoints to a UI or another service.

services/processes/

Put long-running backend processes here.

Examples: - market data ingestion - Momentum Radar scanner - opportunity scanner - strategy allocator - order execution service - risk manager - reconciliation and health workers - scheduled analytics jobs

This is the best home for process-oriented and worker-style runtime logic.

shared/contracts/

Put shared contracts here.

Examples: - order models - event envelopes - Redis stream payload definitions - API request and response schemas - analytics feature schemas

Anything that multiple projects must agree on belongs here.

shared/libraries/

Put reusable shared code here.

Examples: - logging helpers - config loader packages - broker client abstractions - time utilities - retry and idempotency helpers

infrastructure/

Put environment and deployment assets here.

Examples: - Docker Compose - deployment manifests - provisioning scripts - local bootstrap helpers - monitoring setup - cloud infrastructure templates

documentation/

All documentation-related assets should live here.

That includes: - docs source Markdown - MkDocs config - docs-only dependency file - catalog and portal generators - generated docs site output - the transitional static docs portal

This keeps documentation self-contained and easy to move, publish, or maintain independently.

4. Current Practical State

Today, the repository still contains a legacy implementation layout:

  • trading_system/
  • tests/
  • migrations/

That is acceptable for now.

To avoid unnecessary churn, this guide recommends: - do not immediately move the current implementation code unless there is a dedicated refactor task - do move all documentation-platform assets under documentation/ - start placing new projects into the new top-level structure from now on

In other words: - new UI work should go under applications/ - new API work should go under services/apis/ - new worker/process work should go under services/processes/ - existing runtime code can stay where it is until we plan a clean migration

5. Suggested Migration Path

Use this sequence rather than doing one large disruptive move:

  1. finish moving documentation assets under documentation/
  2. create and keep the new top-level folders
  3. place any brand-new UI code in applications/ui/
  4. place any brand-new API code in services/apis/
  5. place any brand-new process code in services/processes/
  6. extract reusable contracts into shared/contracts/
  7. extract shared helpers into shared/libraries/
  8. later, migrate legacy code from trading_system/ in a planned refactor

6. Git Repository Recommendations

To keep the repository clean, I recommend:

Check In

  • applications/
  • services/
  • shared/
  • infrastructure/
  • documentation/
  • tests/
  • migrations/
  • runtime code directories
  • workflow files under .github/

Do Not Check In

  • documentation/site/
  • legacy generated root site/ if it still exists locally
  • virtual environments such as .venv/ and .venv-docs/
  • local secrets such as .env
  • editor and OS noise files

Branch and PR Guidance

As the repo grows, a simple branch naming scheme helps:

  • docs/...
  • ui/...
  • api/...
  • process/...
  • infra/...
  • shared/...

This is not mandatory, but it makes ownership and review context much clearer.

If you decide to continue the cleanup after this structure is adopted, the next good candidates are:

  1. move the FastAPI app into services/apis/
  2. move long-running engine and worker logic into services/processes/
  3. move schemas and event contracts into shared/contracts/
  4. move shared infra files such as docker-compose.yml into infrastructure/local/

These should be done as separate, testable refactors instead of all at once.

8. Best Rule To Follow

Use this simple rule:

  • if humans use it directly, it likely belongs in applications/
  • if it exposes endpoints, it likely belongs in services/apis/
  • if it runs in the background, it likely belongs in services/processes/
  • if multiple projects depend on it, it likely belongs in shared/
  • if it explains, publishes, or supports docs, it belongs in documentation/
  • if it helps environments run or deploy, it belongs in infrastructure/

9. Immediate Recommendation

For the next check-in, I recommend:

  1. commit the documentation platform under documentation/
  2. keep the new top-level folders in place with clear README files
  3. leave the current implementation code where it is for now
  4. start all new work in the new structure instead of expanding the legacy root layout

That gives you a cleaner repository immediately, without forcing a risky code move before you are ready.