Firestore Schema and Relationships Visualization (FSViz)

Extract the schema of a Firestore database, identify relationships between collections, and generate visual representations of the schema and relationships using PlantUML and Mermaid.

Note: this is an exploratory project and not meant for production usage.

See Samples for sample schema, relationship, plantUML, image, and mermaid diagram files.

Features

• Extract Firestore Schema: Retrieve the schema of a Firestore database, including collection names and their fields. Retrieve either a simple list of fields or a full schema with types and occurrence counts.
• Identify Relationships: Use OpenAI's GPT models to identify foreign key relationships between collections.
• Generate PlantUML / Mermaid text: Auto-create textual diagram blocks or full UML diagram definitions (using PlantUML or Mermaid ER shapes) for visualization tools.

Installation

1. Clone the repository

2. Create a virtual environment and activate it:

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables inside your .env file or export them directly:

   export OPENAI_API_KEY='your-api-key'
   export GOOGLE_APPLICATION_CREDENTIALS='path/to/service-account.json'

Usage

This tool now runs via a CLI script called fsviz.py providing multiple commands.

python fsviz.py [-h] [-v] {schema,subcollections,relationships,plantuml,schema-diagram,mermaid} ...

Global Options

• -v, --verbose: Enable verbose output.

1. Extract Schema

Extracts the database schema. Can output a simple list of fields or a full structure indicating object data types and counts.

python fsviz.py schema [--out output_file.json] [--full]

• --out: Overrides default output filename (which defaults to <project_id>.schema.json).
• --full: Outputs a full schema dict indicating types and occurrence counts.

2. Extract Sub-collections Schema

Extracts the database schema for sub-collections of a specific parent collection.

python fsviz.py subcollections <collection_name> [--out output_file.json] [--full] [--limit 100]

• <collection_name>: Name of the parent collection.
• --out: Overrides default output filename (defaults to <project_id>.<collection_name>.schema.json).
• --full: Outputs a full schema dict indicating types and occurrence counts.
• --limit: Number of documents to sample from each collection (defaults to 100).

3. Identify Relationships

Analyzes the schema JSON via OpenAI LLMs to identify the implicit connections between models.

python fsviz.py relationships --schema <schema.json> [--out output_rels.json]

4. Generate PlantUML Diagram

Generates the specific commands used to visualize via PlantUML tools.

python fsviz.py plantuml --schema <schema.json> --relationships <rels.json> [--out output.puml]

#: example
python fsviz.py plantuml --schema samples/sample.schema.json --relationships samples/sample.relationships.json --out samples/sample.puml

5. Generate Mermaid ER Diagram

Generates markdown standard Mermaid ER representations.

python fsviz.py mermaid --schema <schema.json> --relationships <rels.json> [--out output.mmd]

Architecture Notes

• fsviz.py: The main argparse CLI router.
• schema_handler.py: Dedicated file encapsulating Firestore authentication initialization, get_schema, and get_subcollections_schema iterations.
• utils.py: Reusable utilities and generator classes covering OpenAI requests (identify_relationships_llm) and Diagram generations (generate_plantuml_text, generate_mermaid_text).

Credits

Credits: I was inspired by the earlier draft of schema visualizer from https://github.com/analyticalmonk/firestore-schema-visualizer This code enhances and prepares it for the latest version of OpenAI gpt-5.1 models and adds mermaid diagrams besides some other improvements.

License

MIT License