docs: add architecture guidelines and programming standards

[LoyalAbbas]

Summary

Establishes comprehensive Clean Architecture guidelines and programming standards for android-maps3d-samples:

• ARCHITECTURE.md:

  • Specifies architectural blueprints for both 3-way parity demos (Maps3DSamples) and standalone showcase modules (PlacesUIKit3D).
  • Standardizes Repository pattern and domain model decoupling for async SDKs/APIs.
  • Mandates coroutine dispatcher injection for deterministic unit testing.
  • Defines Google Maps 3D SDK standards (explicit AltitudeMode, consumable camera animation commands, and lifecycle forwarding).
  • Documents Jetpack Compose state hoisting and collectAsStateWithLifecycle() standards.
  • Expands 4-tier testing definitions (Engine, Controller/Repository, ViewModel, Visual Regression).
  • Includes explicit incremental adoption rules so maintenance of existing code is never blocked.

• AGENTS.md:

  • Defines AI code generation hygiene (zero wildcard imports, Spotless/ktlint compliance).
  • Establishes modern Kotlin idioms and pragmatic warning hygiene.
  • Sets rules for theme tokens, resource externalization, and cross-module smart casts.

[dkhawk]

Overall this is a fantastic addition! Formalizing Clean Architecture, 3-way parity, the 4-tier testing strategy, and AI pair-programming hygiene is a huge win for maintaining consistency across android-maps3d-samples. The inclusion of the pragmatic, non-blocking incremental adoption rules in GEMINI.md is especially valuable.

Here is some constructive feedback and suggestions for polish:

1. Clarify StateFlow vs LiveData and the asLiveData() approach:

   • Generally speaking, we should keep StateFlow as the standard for Kotlin and Jetpack Compose implementations, and reserve LiveData for Java implementations. Pure Kotlin/Compose modules should rely solely on StateFlow.
   • The asLiveData() approach is primarily relevant for hybrid solutions (like the shared common module in Maps3DSamples/ApiDemos) where a single ViewModel powers Kotlin, Compose, and Java views.
   • For those hybrid ViewModels, using val liveData: LiveData<T> = _uiState.asLiveData() (as currently done in PathFollowingViewModel and AdvancedCameraAnimationViewModel) is much cleaner than manually managing a dual-state _liveData + updateState function with a try/catch block falling back to postValue(). It automatically handles coroutine thread-dispatching and eliminates redundant mutable backing properties.

2. Soft Line Count Guideline for Views (<250 lines):

   • In ARCHITECTURE.md Section 2.A, view layers are noted with a <200 lines target, whereas Sections 1, 2.B, 3, 7, and GEMINI.md cite < 250 lines.
   • While arbitrary hard line limits can be overly rigid, setting a consistent "soft" target of ~250 lines across all sections is a good guideline to keep view layers thin and focused while maintaining consistency throughout the documentation.

3. Markdown / LaTeX Arrow Formatting in ARCHITECTURE.md:

   • In Section 3 (Layer 4), the UDF flow uses LaTeX math syntax $\rightarrow$:
     Views emit user intents $\rightarrow$ ViewModel processes via Repository/Controller $\rightarrow$ Emits immutable State $\rightarrow$ Views render.
   • Replacing $\rightarrow$ with standard Unicode arrows (→ or ->) will ensure clean rendering in all markdown viewers, IDE previews, and mobile GitHub views without relying on KaTeX math rendering.

4. Region Tag Guidance for snippets/ in GEMINI.md:

   • Under Section 4 ("Code Generation Hygiene & Linter Standards"), consider adding a note reminding contributors and AI tools to preserve and utilize region tags (// [START ...] ... // [END ...]) when working in snippets/. This ensures snippet boundaries remain discoverable and compatible with the repository's automated catalog scripts and documentation extractors.

[kikoso]

What if we use an agent neutral markdown file, like AGENTS.md? I assume not everybody will use Gemini.

[kikoso]

What if we align the tree branches for java-app/? It's drawn with └── as the last child of ApiDemos/, but the two lines beneath it still carry the │ │ continuation prefix, which leaves a stray vertical line hanging under a closed branch. Dropping the second pipe would keep the diagram consistent:

│   └── java-app/
│       └── src/main/java/com/example/maps3djava/<feature>/
│           └── <Feature>Activity.java

Purely cosmetic, but since this blueprint is the visual anchor of the doc, it's worth the tidy-up.

[LoyalAbbas]

What if we use an agent neutral markdown file, like AGENTS.md? I assume not everybody will use Gemini.

Good point! I kept it as GEMINI.md because the current implementation and guidelines are strictly tailored to Gemini. I figured it's best to be explicit about what is currently supported. If we expand to other agents later on, we can definitely migrate to an AGENTS.md approach. Let me know if that makes sense!

[kikoso]

What if we use an agent neutral markdown file, like AGENTS.md? I assume not everybody will use Gemini.

Good point! I kept it as GEMINI.md because the current implementation and guidelines are strictly tailored to Gemini. I figured it's best to be explicit about what is currently supported. If we expand to other agents later on, we can definitely migrate to an AGENTS.md approach. Let me know if that makes sense!

I think we should go for the standardization rule, there are not that many differences today between agents, and there will be less differences in the future. This is already a field prone to standardization.

[LoyalAbbas]

What if we use an agent neutral markdown file, like AGENTS.md? I assume not everybody will use Gemini.

Good point! I kept it as GEMINI.md because the current implementation and guidelines are strictly tailored to Gemini. I figured it's best to be explicit about what is currently supported. If we expand to other agents later on, we can definitely migrate to an AGENTS.md approach. Let me know if that makes sense!

I think we should go for the standardization rule, there are not that many differences today between agents, and there will be less differences in the future. This is already a field prone to standardization.

That makes total sense, @kikoso! You're completely right that standardizing on AGENTS.md is more inclusive and forward-looking for the broader developer community, regardless of which agent or tool they use.
I've renamed GEMINI.md to AGENTS.md. Thanks for the suggestion!

[googlemaps-bot]

🎉 This PR is included in version 1.12.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀