docs: add CLAUDE.md and architecture/development docs - #117
Merged
Merged
Conversation
tarruk
approved these changes
Sep 22, 2026
This was referenced Sep 22, 2026
amaury901130
force-pushed
the
docs/claude-md-architecture-docs
branch
from
September 22, 2026 19:55
57799bf to
ca45e47
Compare
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved documentation and example inaccuracies remain across SDK requirements, environment commands, paths, testing, and error handling.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 2
Open (2)
What changed in this PR
Adds comprehensive architecture, development, testing, customization, known-issues, and Rootshift documentation for the Flutter template.
Changes:
- Adds
CLAUDE.mdand links documentation fromREADME.md. - Documents architecture, module boundaries, workflows, and testing.
- Adds feature, bootstrap customization, known-issues, and Rootshift guides.
| File | Change summary | Final review findings |
|---|---|---|
README.md |
Links to the new documentation. | None |
docs/rootshift.md |
Documents Rootshift sidecar integration. | None |
docs/development/testing.md |
Documents testing practices and commands. | L9: Correct the inaccurate claim that all test dependencies are unused. nit (2 votes) |
docs/development/feature-guide.md |
Guides end-to-end feature implementation. | L57: Handle non-Dio parsing/conversion errors. nit (1 vote) L80: Avoid the unchecked Exception-to-Failure cast. nit (1 vote) |
docs/development/bootstrap-customization.md |
Lists new-project customization steps. | L20/L25: Correct missing app/ prefixes or clarify the base directory. nit (1 vote each) |
docs/architecture/overview.md |
Describes implemented architecture and flows. | L165: Correct platform paths that omit app/. nit (1 vote) |
docs/architecture/modules.md |
Defines package responsibilities and boundaries. | None |
docs/architecture/known-issues.md |
Records verified defects and technical debt. | L21: Include the dotenv/JSON failure preceding the documented flavor mismatch. nit (1 vote) |
CLAUDE.md |
Provides the primary developer and agent reference. | L93: Correct the dotenv-versus-JSON environment command. nit (3 votes) L81: Document or align the workspace minimum Dart SDK version. moderate (1 vote) |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| | Format | `dart format app modules`. There is no melos format script (`melos lint:all` calls a missing `format` script and fails). | | ||
| | Regenerate l10n after editing `.arb` | `cd app && dart run intl_utils:generate` | | ||
| | build_runner | `melos pub:runner`. No generators are configured today (see known-issues). | | ||
| | Run (dev) | `cd app && flutter run -t lib/main/env/main_dev.dart --dart-define-from-file=env/.dev` | |
Comment on lines
+9
to
+12
| - The test dependencies are declared but unused: | ||
| - `app`: `flutter_test`, `bloc_test`, `mocktail`, `mockito`, `build_runner` | ||
| - `domain`: `flutter_test`, `mocktail` | ||
| - `data`, `common`: `flutter_test` only |
Document the template as implemented, for developers and AI coding agents: - CLAUDE.md: repo identity, architecture summary, repo map, verified commands, change rules, generated files, definition of done - docs/architecture: overview, module guide (dependency rules), known issues register - docs/development: feature guide, testing guide, bootstrap customization - README: link the docs No code or config changes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
amaury901130
force-pushed
the
docs/claude-md-architecture-docs
branch
from
September 22, 2026 20:03
ca45e47 to
f5b164c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Makes the template understandable to developers and AI coding agents without having to rediscover it. The docs describe the code as it currently is on
main(after #116: FVM, Melos 7 pub workspace), not an idealized architecture.CLAUDE.md: the entry point. It covers what the repo is (a reusable template, not a product), an architecture summary, a repo map, commands derived from the repo, change rules, generated files, pre-implementation steps and a definition of done.docs/architecture/overview.md: layers, the data and state flow (Mermaid), DI order, navigation, networking, persistence, environments and flavors, error handling, l10n, theming and analytics.docs/architecture/modules.md: package responsibilities, allowed and forbidden dependencies (protected boundaries), naming, and how to create a new module in the pub workspace.docs/architecture/known-issues.md: numbered defects and debt items found while reading the source. Nothing was fixed here. Separate PRs cover Create Base GitHub Project #1 (fix(common): make ResultType.mapError invoke its callback #118), Add Localization #2 (fix(domain): fall back to unsuffixed API_URL in EnvConfig.apiUrl #119) and Add Code examples fot Http Client #5 (fix(ios): point flavor xcconfigs at existing entrypoints #120).docs/development/: the feature guide (modelled on the auth example), the testing guide, and the bootstrap customization checklist (what to keep, customize or replace in a new project).README.md: a Documentation section linking the above.No code, config or platform files change.
Issue
N/A
Preview
N/A (docs only)
Notes:
fvm install,melos bootstrap,melos run analyze,melos run format,melos exec --dir-exists=test -- flutter test) match the new rootpubspec.yamlscripts and the CI workflow.main:sonar-qube-scann.ymlfails at its first step because theSSH_PRIVATE_KEYsecret isn't configured, so analyze and the tests never run. No pub dependency is git-based, so thessh-agentstep can simply be removed. This is recorded as known-issues Add Basic Theme Structure #3, and this PR's check fails for the same reason..cursor/rulesand.github/instructionswere left untouched.CLAUDE.mdstates that it anddocs/take precedence where they conflict (known-issues Add Tech Guides in the Company Repo #15).🤖 Generated with Claude Code