docs: link subpackages to architecture map

[WilliamK112]

Summary

• add the requested ARCHITECTURE.md breadcrumb to every top-level subpackage listed in the architecture map
• keep the change limited to package docstrings, with no runtime behavior changes
• make source-first browsing lead contributors back to the repository map

Closes #161.

Validation

• ruff check .
• mypy --python-version 3.12 src/freshdata — 201 source files
• pytest -m "not online and not large" — 4,051 passed, 6 skipped, 12 deselected; 93.16% coverage
• git diff --check

Summary by CodeRabbit

• Documentation
  • Added references to the architecture guide across package documentation.
  • Clarified the roles of key internal processing areas, including imputation and data-cleaning integrations.
  • No functionality, exports, or public behavior changed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3d73b648-7c27-4a7d-b221-53197b8bcd6a

📥 Commits

Reviewing files that changed from the base of the PR and between 33f50fa and 3deb9b3.

📒 Files selected for processing (17)

• src/freshdata/adapters/__init__.py
• src/freshdata/compliance/__init__.py
• src/freshdata/context/__init__.py
• src/freshdata/domains/__init__.py
• src/freshdata/engine/__init__.py
• src/freshdata/enterprise/__init__.py
• src/freshdata/execution/__init__.py
• src/freshdata/experimental/__init__.py
• src/freshdata/imputation/__init__.py
• src/freshdata/integrations/__init__.py
• src/freshdata/learning/__init__.py
• src/freshdata/models/__init__.py
• src/freshdata/parsers/__init__.py
• src/freshdata/render/__init__.py
• src/freshdata/semantic/__init__.py
• src/freshdata/steps/__init__.py
• src/freshdata/streaming/__init__.py

🚧 Files skipped from review as they are similar to previous changes (17)

• src/freshdata/parsers/init.py
• src/freshdata/execution/init.py
• src/freshdata/imputation/init.py
• src/freshdata/semantic/init.py
• src/freshdata/steps/init.py
• src/freshdata/enterprise/init.py
• src/freshdata/context/init.py
• src/freshdata/models/init.py
• src/freshdata/learning/init.py
• src/freshdata/render/init.py
• src/freshdata/integrations/init.py
• src/freshdata/engine/init.py
• src/freshdata/adapters/init.py
• src/freshdata/domains/init.py
• src/freshdata/streaming/init.py
• src/freshdata/experimental/init.py
• src/freshdata/compliance/init.py

---

📝 Walkthrough

Walkthrough

Seventeen subpackage docstrings now link to ARCHITECTURE.md. No exports, imports, or executable behavior changed.

Changes

Architecture documentation links

Layer / File(s)	Summary
Add architecture references src/freshdata/*/__init__.py	Package docstrings now reference ARCHITECTURE.md. The adapter and imputation docstrings also include expanded package descriptions.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• FreshCode-Org/freshdata#158: Adds the architecture documentation referenced by these package docstrings.

Suggested reviewers: kevincostner17

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes linking subpackages to the architecture map.
Description check	✅ Passed	The description summarizes the documentation change, references issue #161, and records validation results, but omits template headings and checklist items.
Linked Issues check	✅ Passed	The changes satisfy issue #161 by adding architecture breadcrumbs to all 17 listed subpackage docstrings without behavior changes.
Out of Scope Changes check	✅ Passed	All changes are limited to documentation updates in the subpackages identified by issue #161.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[strix-security]

Strix is installed on this repository, but we couldn't run this PR security review because this workspace's trial has ended. Add a card to resume code reviews here.

So far, Strix has reviewed 36 pull requests, surfaced 3 security issues (1 critical/high) and blocked 1 risky merge across this workspace.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 33f50fa05b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make the architecture breadcrumb an actual link

The double-backtick syntax renders ARCHITECTURE.md only as inline code and provides no hyperlink target. This same addition appears in every changed package, so readers viewing the generated docstring or browsing an src/freshdata/<package>/__init__.py cannot follow the promised breadcrumb to the repository-root file. Use an explicit repository URL or another valid link target so the source-first navigation described by this change actually works.

Useful? React with 👍 / 👎.

[WilliamK112]

Addressed in 3deb9b3: all 17 added breadcrumbs now use an explicit reStructuredText link to the repository-root ARCHITECTURE.md, so they are clickable both in rendered docstrings and from source-oriented documentation. Revalidation passed Ruff, mypy across 201 source files, the 17/17 docstring-link check, git diff --check, and the full fast lane (4,051 passed, 6 skipped; 93.16% coverage).

[kevincostner17]

Verdict: Valid — approve

Checked against #161 acceptance criteria.

Acceptance criteria (#161)

Criterion	Status
Docstrings only — no behavior change	Pass — only __init__.py docstrings touched, +55/−2
ruff check . and mypy src/freshdata pass	Pass (CI green)
Fast test lane stays green	Pass — 4,051 passed, 93.16% coverage

Verification

• All 17 subpackages listed in issue #161 have the breadcrumb: engine, steps, imputation, domains, semantic, context, enterprise, compliance, execution, streaming, parsers, render, models, learning, integrations, adapters, experimental. ✓
• ARCHITECTURE.md exists on main (added in #158). Link URL is correct. ✓
• import freshdata works fine after the change. ✓
• The breadcrumb text is consistent across all 17 files — same RST link format, same wording. ✓
• Adapters and imputation docstrings got slightly expanded descriptions alongside the breadcrumb, which is a nice touch. ✓

CI

All checks green: quality-fast, truthbench, test-matrix (3.9–3.13), build, benchmark, plugin-contract, reproducibility, gauntlet, wheel-guard.

Clean, mechanical docs PR — exactly what #161 asked for. Good to merge.