Increment 1: Foundation

.clang-format

@@ -0,0 +1,48 @@
+# Modulo C++ formatting rules.
+# Applied by scripts/format.sh using clang-format from /opt/homebrew/opt/llvm/bin.
+---
+Language: Cpp
+BasedOnStyle: LLVM
+Standard: Latest
+
+# Layout
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ColumnLimit: 120
+AccessModifierOffset: -4
+IndentPPDirectives: BeforeHash
+NamespaceIndentation: None
+FixNamespaceComments: true
+InsertNewlineAtEOF: true
+
+# Pointers & references bind to the type: `int* p`, `const QString& s`.
+PointerAlignment: Left
+ReferenceAlignment: Left
+DerivePointerAlignment: false
+
+# Declarations
+BreakTemplateDeclarations: Yes
+AllowShortFunctionsOnASingleLine: InlineOnly
+AllowShortLambdasOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+SeparateDefinitionBlocks: Always
+
+# Include ordering: main header first (clang-format default), then local "quoted",
+# then project <modulo/...>, then Qt, then third-party, then the C++ standard library.
+SortIncludes: CaseSensitive
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^"'
+    Priority: 1
+  - Regex: '^<modulo/'
+    Priority: 2
+  - Regex: '^<Q'
+    Priority: 3
+  - Regex: '^<(pqxx|sodium)'
+    Priority: 4
+  - Regex: '^<[a-z_0-9]+(\.h)?>$'
+    Priority: 5
+  - Regex: '.*'
+    Priority: 4

.clang-tidy

@@ -0,0 +1,40 @@
+# Modulo static-analysis rules.
+# Run via the `dev-tidy` CMake preset (clang-tidy from /opt/homebrew/opt/llvm/bin).
+#
+# Check families: bugprone, performance, modernize, readability.
+# Suppressions (kept deliberately short):
+#   - bugprone-easily-swappable-parameters: too noisy for small DTO/ctor signatures.
+#   - modernize-use-trailing-return-type: we use classic return-type style.
+#   - modernize-use-nodiscard: project decision — no [[nodiscard]] on declarations.
+#   - readability-identifier-length: short names (id, tx, db) are idiomatic here.
+#   - readability-magic-numbers: config defaults and test literals would drown the signal.
+---
+Checks: >
+  bugprone-*,
+  performance-*,
+  modernize-*,
+  readability-*,
+  -bugprone-easily-swappable-parameters,
+  -modernize-use-trailing-return-type,
+  -modernize-use-nodiscard,
+  -readability-identifier-length,
+  -readability-magic-numbers
+
+WarningsAsErrors: ''
+HeaderFilterRegex: '.*/(include|src)/modulo/.*|.*/(libs|server|client)/.*\.h$'
+FormatStyle: file
+
+CheckOptions:
+  # Naming: CamelCase types, camelBack functions/variables, snake_case namespaces,
+  # trailing underscore for private members, UPPER_CASE macros.
+  readability-identifier-naming.NamespaceCase: lower_case
+  readability-identifier-naming.ClassCase: CamelCase
+  readability-identifier-naming.StructCase: CamelCase
+  readability-identifier-naming.EnumCase: CamelCase
+  readability-identifier-naming.EnumConstantCase: CamelCase
+  readability-identifier-naming.FunctionCase: camelBack
+  readability-identifier-naming.VariableCase: camelBack
+  readability-identifier-naming.ParameterCase: camelBack
+  readability-identifier-naming.PrivateMemberSuffix: '_'
+  readability-identifier-naming.MacroDefinitionCase: UPPER_CASE
+  readability-function-cognitive-complexity.IgnoreMacros: true

.env.example

@@ -0,0 +1,18 @@
+# Modulo environment configuration.
+# Copy to `.env` and adjust; `.env` is gitignored — NEVER commit real values.
+
+# PostgreSQL connection for the server and the migration runner.
+# Port 5433 is deliberate: the dockerized Postgres 16 maps there to avoid the
+# local Homebrew PostgreSQL 14 already listening on 5432.
+MODULO_DB_URL=postgresql://modulo:modulo@localhost:5433/modulo_dev
+
+# Test database used by integration tests (`ctest --preset integration`).
+# When unset, integration tests SKIP cleanly instead of failing.
+MODULO_TEST_DB_URL=postgresql://modulo:modulo@localhost:5433/modulo_test
+
+# Port the REST API listens on (localhost only during development).
+MODULO_HTTP_PORT=8080
+
+# Root directory for server-managed files (uploaded documents live under
+# documents/<uuid>). Gitignored; becomes a mounted volume when containerized.
+MODULO_DATA_DIR=./var/data

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+# Continuous integration: configure + build (-Werror), formatting check, and the
+# unit + UI test suites on a macOS runner (the project's primary platform).
+#
+# Integration tests need PostgreSQL, which macOS runners cannot provide via
+# Docker; they are opt-in (MODULO_TEST_DB_URL) and therefore report as Skipped
+# here. A Linux job with a Postgres service container arrives with the
+# containerized backend (Increment 9).
+
+name: CI
+
+on:
+  push:
+    branches: [main, "increment-*"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    name: Build & test (macOS, Apple Silicon)
+    runs-on: macos-15
+    timeout-minutes: 45
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        # clang-format (small formula) instead of the full llvm keg; scripts/format.sh
+        # picks it up through CLANG_FORMAT.
+        run: brew install ninja qt libpq libpqxx libsodium clang-format
+
+      - name: Show toolchain versions
+        run: |
+          cmake --version | head -1
+          ninja --version
+          brew list --versions qt libpqxx libsodium clang-format
+          "$(brew --prefix clang-format)/bin/clang-format" --version
+
+      - name: Configure
+        run: cmake --preset ci
+
+      - name: Build
+        run: cmake --build --preset ci
+
+      - name: Check formatting
+        env:
+          CLANG_FORMAT: /opt/homebrew/opt/clang-format/bin/clang-format
+        run: scripts/format.sh --check
+
+      - name: Run tests (unit + ui; integration skips without a database)
+        run: ctest --preset ci

.gitignore

@@ -54,3 +54,10 @@ compile_commands.json
 *creator.user*
 
 *_qmlcache.qrc
+
+# Modulo
+build*/
+var/
+.env
+.cache/
+.DS_Store

CMakeLists.txt

@@ -0,0 +1,37 @@
+# Modulo — personal investment tracker.
+#
+# Contains options, toolkit includes, dependency resolution and subdirectory wiring.
+# All build logic is implemented as modulo_* functions in cmake/ (see cmake/ModuloTargets.cmake).
+
+cmake_minimum_required(VERSION 3.28)
+
+project(
+    Modulo
+    VERSION 0.1.0
+    DESCRIPTION "Personal investment tracker"
+    LANGUAGES CXX)
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
+
+# --- Options (set via CMakePresets.json) -------------------------------------
+option(MODULO_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
+option(MODULO_BUILD_TESTS "Build the test suites" ON)
+option(MODULO_CLANG_TIDY "Run clang-tidy during compilation" OFF)
+set(MODULO_SANITIZERS
+    ""
+    CACHE STRING "Comma-separated -fsanitize= list, e.g. 'address,undefined'")
+
+# --- Toolkit & dependencies --------------------------------------------------
+include(ModuloTargets)
+include(Dependencies)
+modulo_find_dependencies()
+
+qt_standard_project_setup(REQUIRES 6.8)
+
+enable_testing()
+
+# --- Project targets ---------------------------------------------------------
+add_subdirectory(libs/core)
+add_subdirectory(libs/api)
+add_subdirectory(server)
+add_subdirectory(client)

CMakePresets.json

@@ -0,0 +1,137 @@
+{
+    "version": 6,
+    "cmakeMinimumRequired": {
+        "major": 3,
+        "minor": 28,
+        "patch": 0
+    },
+    "configurePresets": [
+        {
+            "name": "base",
+            "hidden": true,
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build/${presetName}",
+            "cacheVariables": {
+                "CMAKE_PREFIX_PATH": "/opt/homebrew/opt/qt",
+                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+                "WrapOpenGL_AGL": "/Library/Developer/CommandLineTools/SDKs/MacOSX15.4.sdk/System/Library/Frameworks/AGL.framework",
+                "PostgreSQL_ROOT": "/opt/homebrew/opt/libpq"
+            }
+        },
+        {
+            "name": "dev",
+            "displayName": "Development (Debug, warnings-as-errors)",
+            "inherits": "base",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Debug",
+                "MODULO_WARNINGS_AS_ERRORS": "ON"
+            }
+        },
+        {
+            "name": "dev-asan",
+            "displayName": "Development + address/UB sanitizers",
+            "inherits": "dev",
+            "cacheVariables": {
+                "MODULO_SANITIZERS": "address,undefined"
+            }
+        },
+        {
+            "name": "dev-tidy",
+            "displayName": "Development + clang-tidy on every compile",
+            "inherits": "dev",
+            "cacheVariables": {
+                "MODULO_CLANG_TIDY": "ON"
+            }
+        },
+        {
+            "name": "release",
+            "displayName": "Release (RelWithDebInfo)",
+            "inherits": "base",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "RelWithDebInfo"
+            }
+        },
+        {
+            "name": "ci",
+            "displayName": "Continuous integration (GitHub Actions macOS runner)",
+            "inherits": "dev",
+            "cacheVariables": {
+                "WrapOpenGL_AGL": ""
+            }
+        }
+    ],
+    "buildPresets": [
+        {
+            "name": "dev",
+            "configurePreset": "dev"
+        },
+        {
+            "name": "dev-asan",
+            "configurePreset": "dev-asan"
+        },
+        {
+            "name": "dev-tidy",
+            "configurePreset": "dev-tidy"
+        },
+        {
+            "name": "release",
+            "configurePreset": "release"
+        },
+        {
+            "name": "ci",
+            "configurePreset": "ci"
+        }
+    ],
+    "testPresets": [
+        {
+            "name": "unit",
+            "configurePreset": "dev",
+            "filter": {
+                "include": {
+                    "label": "^unit$"
+                }
+            },
+            "output": {
+                "outputOnFailure": true
+            }
+        },
+        {
+            "name": "integration",
+            "configurePreset": "dev",
+            "filter": {
+                "include": {
+                    "label": "^integration$"
+                }
+            },
+            "output": {
+                "outputOnFailure": true
+            }
+        },
+        {
+            "name": "ui",
+            "configurePreset": "dev",
+            "filter": {
+                "include": {
+                    "label": "^ui$"
+                }
+            },
+            "output": {
+                "outputOnFailure": true
+            }
+        },
+        {
+            "name": "all",
+            "configurePreset": "dev",
+            "output": {
+                "outputOnFailure": true
+            }
+        },
+        {
+            "name": "ci",
+            "configurePreset": "ci",
+            "output": {
+                "outputOnFailure": true
+            }
+        }
+    ]
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angelo Barbu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.