docs(firestore): Improving discoverability and giving more product context

Author: rafikhan

packages/firestore/CONTRIBUTING.md

@@ -5,6 +5,8 @@ contributing to the Firebase JavaScript SDK (including Cloud Firestore).
 Follow instructions there to install dependencies, build the SDK, and set up
 the testing environment.
 
+For a deep dive into the testing strategy and architecture, see [Testing Strategy](devdocs/testing.md).
+
 ## Integration Testing
 
 ### Setting up a project for testing

packages/firestore/README.md

@@ -17,6 +17,10 @@ Docs][reference-docs].
 
 [reference-docs]: https://firebase.google.com/docs/reference/js/
 
+## Internal Documentation
+
+If you are a contributor or maintainer, please see the [Internal Developer Documentation](./devdocs/overview.md).
+
 ## Contributing
 See [Contributing to the Firebase SDK](../../CONTRIBUTING.md) for general
 information about contributing to the firebase-js-sdk repo and

packages/firestore/devdocs/architecture.md

@@ -12,6 +12,7 @@ The SDK is composed of several key components that work together to provide the
 *   **Core**:
     *   **Event Manager**: Acts as a central hub for all eventing in the SDK. It is responsible for routing events between the API Layer and Sync Engine. It manages query listeners and is responsible for raising snapshot events, as well as handling connectivity changes and some query failures.
 *   **Sync Engine**: The central controller of the SDK. It acts as the glue between the Event Manager, Local Store, and Remote Store.
+    *   **Target**: The backend protocol's internal representation of a recurring Query. While a `Query` is a user-intent (e.g., "users where age > 18"), a `Target` is the allocated stream ID (`TargetID`) that the Watch implementation uses to track that query's state over the network. The **Coordinator** maps ephemeral user Queries to stable system Targets.
     *   **Coordinator**: It bridges the **User World** (Query) and **System World** (Target), converting public API calls into internal `TargetIDs`.
     *   **View Construction**: It manages the user-facing view using the formula: `View = Remote Document + Overlay`.
         *   **Remote Document**: The authoritative state from the backend.

packages/firestore/devdocs/build.md

@@ -1,3 +1,5 @@
 # Build Process
 
-This document provides a detailed explanation of the Firestore JavaScript SDK build process for the main and lite packages.
+> **Note**: This documentation is currently under construction and will be updated soon.
+
+For current build instructions, test commands, and setup, please go to [CONTRIBUTING.md](../CONTRIBUTING.md).

packages/firestore/devdocs/overview.md

@@ -16,11 +16,21 @@ The primary goals of this SDK are:
 *   Offer a lightweight version for applications that do not require advanced features.
 *   Maintain API and architectural symmetry with the [Firestore Android SDK](https://github.com/firebase/firebase-android-sdk) and [Firestore iOS SDK](https://github.com/firebase/firebase-ios-sdk). This consistency simplifies maintenance and makes it easier to port features between platforms. The public API is intentionally consistent across platforms, even if it means being less idiomatic, to allow developers to more easily port their application code.
 
+## Designed for Flicker-Free Responsiveness
+
+Firestore is designed to help developers build responsive front-end applications that eliminate UI flicker.
+
+1.  **Immediate Cache Results**: The SDK returns query results from the local cache immediately, while fetching the latest data from the server in the background.
+2.  **Optimistic Updates**: Writes are applied to the local cache *instantly*, allowing the UI to update without waiting for network confirmation.
+3.  **Background Synchronization**: The SDK handles the network communication to commit these changes to the backend asynchronously.
+
+*This means the "Happy Path" handles latency automatically. You don't write special code to manage loading states for every interaction; the SDK provides instant feedback by default.*
+
 
 ## Key Concepts & Vocabulary
 
 *   **Query**: The client-side representation of a data request (filters, order bys).
-*   **Target**: The backend's representation of a Query. The SDK allocates a unique integer `TargetID` for every unique query to manage the real-time stream.
+
 *   **Mutation**: A user-initiated change (Set, Update, Delete). Mutations are queued locally and sent to the backend.
 *   **Overlay**: The computed result of applying a Mutation to a Document. We store these to show "Optimistic Updates" instantly without modifying the underlying "Remote Document" until the server confirms the write.
 *   **Limbo**: A state where a document exists locally and matches a query, but the server hasn't explicitly confirmed it belongs to the current snapshot version. The SDK must perform "Limbo Resolution" to ensure these documents are valid.
@@ -39,6 +49,9 @@ The Firestore JavaScript SDK is divided into two main packages:
 
 To navigate the internals of the SDK, use the following guide:
 
+### Getting Started (Build & Run)
+*   **[Start Here: Build & Run](../CONTRIBUTING.md)**: How to set up the repo, build the SDK, and run tests.
+
 ### Core Concepts
 *   **[Architecture](./architecture.md)**: The high-level block diagram of the system (API -> Core -> Local -> Remote).
 *   **[Query Lifecycle](./query-lifecycle.md)**: The state machine of a query. **Read this** to understand how querying and offline capabilities work.
@@ -56,5 +69,4 @@ To navigate the internals of the SDK, use the following guide:
 *   **[Code Layout](./code-layout.md)**: Maps the architectural components to specific source files and directories.
 *   **[Build Process](./build.md)**: How to build the artifacts.
 *   **[Testing](./testing.md)**: How to run unit and integration tests.
-*   **[Spec Tests](./spec-tests.md)**: Deep dive into the cross-platform JSON test suite.
-*   **[Contributing](../CONTRIBUTING.md)**: How to run unit and integration tests.
+*   **[Spec Tests](./spec-tests.md)**: Deep dive into the cross-platform JSON test suite.

packages/firestore/devdocs/prerequisites.md

@@ -23,7 +23,7 @@ Before contributing to this codebase, you should have a strong understanding of
 
 ### Domain Knowledge
 
-*   **[Google Cloud Firestore](https://firebase.google.com/docs/firestore):** A deep understanding of Firestore's data model (documents, collections, subcollections), query language, and security rules is fundamental.
+*   **[Google Cloud Firestore](https://firebase.google.com/docs/firestore):** A general understanding of Firestore's data model (documents, collections, subcollections), query language, and security rules is fundamental.
 *   **Databases:** A general understanding of databases, including key-value stores and relational databases, is helpful for understanding Firestore's design and trade-offs.
 *   **Modern Web Application Architecture:** Familiarity with modern web application architecture and also server-side rendering (SSR), is beneficial for understanding how the SDK is used in practice.
 *   **[Firebase](https://firebase.google.com/docs):** Familiarity with the Firebase platform is required, especially Firebase Auth and Firebase Functions.

packages/firestore/devdocs/testing.md

@@ -1,4 +1,4 @@
-# Build Process
+# Testing Strategy
 
 This document provides a detailed explanation of the Firestore JavaScript SDK testing strategy, tech stack, and patterns and practices.
 
@@ -27,21 +27,5 @@ The Firestore JS SDK employs a three-tiered testing strategy to ensure reliabili
 *   **Purpose**: Verifying that the client protocol actually matches what the real backend server expects.
 *   **Behavior**: These tests create real writes and listeners. They are slower and subject to network timing, but essential for catching protocol drifts.
 
-## Running Tests
-
-### Unit & Spec Tests
-Run via Karma.
-```bash
-yarn test
-```
-
-### Integration Tests
-Requires the Firebase Emulator Suite running.
-```bash
-# Start emulators
-yarn emulators:start
-
-# In another terminal, run integration tests
-yarn test:integration
-```
+> **Note**: For instructions on how to run these tests, see **[CONTRIBUTING.md](../CONTRIBUTING.md)**.