mirror of
https://github.com/sebastiandine/Card-Collection-Manager-3.git
synced 2026-08-28 17:01:02 +00:00
Sebastian Dine
55ace147bc
* initial development * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * pokemon * pokemon * pokemon * pokemon * pokemon * pokemon * improvements * improvements * ci/cd * ci/cd * improvements * improvements * improvements * improvements * improvements * improvements * improvements * improvements * improvements --------- Co-authored-by: sdine <sdine@sdine.com>
109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
#documentation #onboarding #architecture
|
|
|
|
# Intro For New Developers
|
|
|
|
This document orients new contributors to Card Collection Manager 3. For local setup and build commands, start with [Build Locally Guide](dow-doc-build-locally.md); then use this guide to understand architecture boundaries and daily workflows.
|
|
|
|
**Quick Setup:** read `AGENTS.md` files first, build once, run tests once, then make one small layer-scoped change to validate your environment.
|
|
|
|
## Toolchain Snapshot
|
|
|
|
Card Collection Manager 3 builds as a native C++ desktop binary with CMake. The project standard is C++20, with Clang as the preferred compiler on Windows and Linux, plus a verified MinGW-w64 fallback path on Windows.
|
|
|
|
- build system: CMake 3.22+ with `FetchContent`
|
|
- language/toolchain: C++20, Clang preferred, MinGW-w64 GCC fallback on Windows
|
|
- UI toolkit: wxWidgets (`ui_wx/` only)
|
|
- REST/HTTP client library: `cpr` (libcurl-based, used through `IHttpClient`/`CprHttpClient`)
|
|
- JSON library: `nlohmann/json`
|
|
- test framework: `doctest`
|
|
|
|
Use [Build Locally Guide](dow-doc-build-locally.md) for exact commands, generator options, runtime DLL notes, and troubleshooting details.
|
|
|
|
## Project Shape
|
|
|
|
Card Collection Manager 3 is a native desktop app written in C++20 with wxWidgets. The architecture is intentionally layered so core logic stays UI-agnostic.
|
|
|
|
- `core/`: domain logic, services, and infrastructure adapters
|
|
- `ui_wx/`: wxWidgets UI code only
|
|
- `app/`: composition root that wires adapters, services, and views
|
|
|
|
Dependency direction is strict: `app -> ui_wx -> core`.
|
|
|
|
## Architecture Rules
|
|
|
|
These rules are the baseline for all feature work:
|
|
|
|
- `core/` must never include or depend on wxWidgets.
|
|
- UI code consumes services through `ccm::ui::AppContext`.
|
|
- Concrete adapter wiring belongs in `app/main.cpp`.
|
|
- JSON keys and aliases are contract-sensitive and must stay stable.
|
|
|
|
## Repository Map
|
|
|
|
### `core/`
|
|
|
|
`core/` contains domain and non-UI behavior:
|
|
|
|
- `domain/`: value types and enums (`MagicCard`, `PokemonCard`, `Set`, `Configuration`)
|
|
- `ports/`: seam interfaces (`IHttpClient`, `IFileSystem`, repositories, game seams)
|
|
- `services/`: use-case logic (`CollectionService`, `SetService`, `ConfigService`)
|
|
- `infra/`: concrete adapters (`Json*Repository`, `StdFileSystem`, `CprHttpClient`, `LocalImageStore`)
|
|
- `games/`: per-game modules (`magic`, `pokemon`)
|
|
|
|
### `ui_wx/`
|
|
|
|
`ui_wx/` contains all presentation code:
|
|
|
|
- `MainFrame`: top-level shell and menu/split-view orchestration
|
|
- `BaseCardListPanel`, `BaseCardEditDialog`, `BaseSelectedCardPanel`: reusable UI templates
|
|
- `Magic*` and `Pokemon*` classes: game-specific view/panel implementations
|
|
- `Theme.cpp`, `SvgIcons.cpp`, `IconListCtrl.cpp`: theming and visual behavior
|
|
|
|
### `app/`
|
|
|
|
`app/main.cpp` is the composition root:
|
|
|
|
- instantiate adapters, services, and modules
|
|
- register game modules and game views
|
|
- build `AppContext`
|
|
- create and show `MainFrame`
|
|
|
|
Keep this file focused on wiring, not business logic.
|
|
|
|
### `tests/`
|
|
|
|
Tests target non-UI behavior with deterministic fakes and in-memory adapters. When a domain JSON contract or filesystem naming rule changes, update the matching tests in the same change.
|
|
|
|
## Common Workflows
|
|
|
|
### Add A Small Feature
|
|
|
|
1. Identify the correct layer (`core`, `ui_wx`, or both).
|
|
2. Make the smallest coherent change in that layer.
|
|
3. Rebuild the affected target.
|
|
4. Run tests when core behavior changes.
|
|
|
|
### Add A New Game
|
|
|
|
Use [Adding a new game to Card Collection Manager](adding-a-new-game.md). Do not bypass the existing seams or invent parallel architecture for a new game.
|
|
|
|
### Release-Oriented Changes
|
|
|
|
Use [CI/CD Guide](ci-cd-guide.md) and [Versioning Guide](versioning.md) for workflow and release policy decisions.
|
|
|
|
## Avoid These Pitfalls
|
|
|
|
- adding wx headers in `core/`
|
|
- putting business logic in `app/main.cpp`
|
|
- accessing concrete adapters directly from UI code instead of `AppContext`
|
|
- changing JSON key spellings casually
|
|
- using unpinned dependency versions
|
|
|
|
## First-Day Checklist
|
|
|
|
1. Read repository `AGENTS.md` files (`core/`, `ui_wx/`, `app/`, `tests/`).
|
|
2. Build locally with [Build Locally Guide](dow-doc-build-locally.md).
|
|
3. Run the test suite once.
|
|
4. Make one small layer-contained change.
|
|
5. Rebuild and rerun relevant tests.
|