Add comprehensive codebase reference guide

[SwatX18]

Summary

Adds docs/CODEBASE_GUIDE.md — a complete technical reference for the vibranceGUI codebase, written for new contributors and AI coding agents with no prior context on the project.

2,213 lines · 14 sections · 4 mermaid diagrams · 335 file:line citations

Sections: what the program does → orientation TL;DR → tech stack & build → repository map → architecture → the runtime story end-to-end → the NVIDIA path → the AMD path → settings & persistence → UI surface → data models → defect & risk register → extension guide → open questions.

Documentation only. No source files are modified.

What it covers

• The foreground-detection mechanism (a single EVENT_SYSTEM_FOREGROUND WinEvent hook) and the apply/revert decision that is the heart of the app.
• Both vendor paths in depth, including a PE and disassembly pass over the prebuilt vibranceDLL.dll — whose source is not in this repository — recovering the NvAPI interface IDs it resolves, the calling-convention constraints, and per-export behaviour.
• Exact settings file locations and formats, the autostart mechanism, and the silent-degradation behaviour on corrupt or missing files.
• A 57-item defect and risk register, each entry cited to file:line.

Findings that contradict reasonable assumptions

These are the ones most likely to save a contributor time, because each one is the opposite of what the code appears to promise:

• Costura.Fody does not embed vibranceDLL.dll. A plain MSBuild <EmbeddedResource> does, extracted by hand at runtime to %APPDATA%. Costura is nearly a no-op today.
• SetVibranceIngameLevel is a no-op. userVibranceSettingActive is written by both proxies and read nowhere, so the ingame slider's live preview does nothing.
• The adl32/adl64 folder names are effectively backwards. adl64 loads the 32-bit atiadlxy.dll; the split is by OS bitness, not process bitness. 940 lines of duplication carry a single string literal.
• The released v2.5.0 tag is not an ancestor of master. It lives on the unmerged feature/add-color-settings branch (PR Feature/add color settings juv/vibranceGUI#140 upstream), so master ships older behaviour than the published release.
• Foreground matching is by ProcessName only — the executable path is ignored entirely.
• The Count > 0 guard wraps both the apply and revert branches, so removing the last watched app while ingame strands vibrance at the ingame level.

Upstream issues explained

Mechanisms behind several open upstream issues are documented — juv#138 (a non-terminating enumeration loop, because the native call returns 0 rather than -1 on any error other than end-of-enumeration), juv#114/juv#132 (DispChangeBadflags raised modally from inside the foreground callback, and repeating because the guard condition stays true), juv#150/juv#145/juv#142 (hybrid-GPU systems detected as Ambiguous), and juv#144.

These are explicitly labelled as inference in the document. They are derived from reading the code, not confirmed at runtime.

Verification

A review pass sampled ~215 of 335 citations against the actual source and read every hand-written .cs file end to end.

Verdict: ship with fixes — 1 blocking, 12 minor, all applied and re-verified.

• Blocking: a ; inside a mermaid sequence-diagram message terminated the parser's lexer; GitHub would have rendered a red error box instead of the startup diagram. Fixed and confirmed rendering.
• Minor: count and citation corrections (3 of ~60 → 2 of 71 constants; NvidiaTypes.cs:18-19 → :14-15; one overstated "unconditionally").

Independently confirmed during review: all four headline corrections above, the value ranges and clamping behaviour, the match rule, the Count > 0 guard, every quoted user-facing string, all build facts, and the binary analysis (8 named RVAs spot-decoded, matching byte-for-byte).

Assumptions and limits

• Nothing was built or executed. This is a static analysis; the document says so itself.
• Issue-cause explanations are inference, marked as such. 23 hedging markers were verified to land on exactly those claims — the review found no place where an inference is restated as settled fact.
• GitHub issue titles and numbers could not be verified offline.
• Coverage gaps recorded by the reviewer: ~120 citations unsampled; 11 of the 13 NvAPI ID lookups not decoded; the KERNEL32 import count not confirmed; four commit-message quotations not checked against git log.

🤖 Generated with Claude Code

https://claude.ai/code/session_0187tGqyEw4frZzDYPPJfUMd