# us-check/server-firestore architecture

> Architecture diagram of the GitHub repository us-check/server-firestore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/us-check/server-firestore
- Repository: https://github.com/us-check/server-firestore

## Overview

##### Project Type and Purpose
- This is a backend service built with Django (Python) whose primary role is to expose RESTful endpoints (in `uscheck_firestore/api/`) and to synchronize or migrate data into Google Firestore (via code in `uscheck_firestore/firestore/` and the script `upload_json_to_firestore.py`).
- It also integrates with Google Cloud Platform (GCP) components—Cloud Storage (for file uploads/exports), Pub/Sub (for asynchronous messaging), and Cloud Functions (for event-driven processing).

##### Key Elements from the File Structure
- Top-level Django project (`uscheck_firestore/uscheck_firestore/`): settings, URLs, WSGI/ASGI entry points.
- Two Django apps:
- `api/` – Models, views, serializers (if any), URLs that define the HTTP API.
- `firestore/` – Code for interacting with Firestore: models, services, and views likely used internally or administratively.
- Management script `upload_json_to_firestore.py` for bulk data ingestion.
- `requirements.txt` defines Python dependencies (e.g., Django, google-cloud-firestore, google-cloud-storage, etc.).

##### Architectural Patterns and Design Principles
- MVC (Django’s MVT) pattern:
- Models in each app (`models.py`)
- Views/Controllers (`views.py`, `api/services.py`)
- URL routing layer (`urls.py`)
- Service layer abstraction (`api/services.py`) to encapsulate business logic.
- Event-driven integration with GCP: Pub/Sub topics and Cloud Functions subscribe to storage or messaging events.

##### Main Components
a. Django Backend (Compute Engine / App Engine / GKE)
- HTTP(S) Load Balancer → Django application servers
- Internal modules: API app, Firestore app, Management scripts
b. Firestore Database
- Two Firestore collections (e.g., tour data, user data)
c. Google Cloud Storage (GCS)
- Bucket(s) used for uploading source JSON files (`us_tourdata_final.txt`), storing exports/backups
d. Pub/Sub
- Topics for “new file uploaded” and “data ingest complete” events
e. Cloud Functions
- Triggered by GCS “OBJECT_FINALIZE” events and Pub/Sub messages
- Perform parsing, call Django’s ingestion endpoints or call Firestore SDK directly
f. External Clients
- CLI or web clients consuming the REST API

##### Relationships and Data Flows
- External client → (1) HTTP POST/GET → Load Balancer → Django API → (2) Firestore SDK → Firestore
- Management script (`upload_json_to_firestore.py`) → (3) directly writes to Firestore via SDK
- Client uploads JSON to GCS → (4) GCS “OBJECT_FINALIZE” event → Pub/Sub → (5) Cloud Function → (6) HTTP request to Django ingestion endpoint / direct Firestore write
- Django publishes a status message → (7) Pub/Sub topic “ingest-complete” → downstream subscribers or Cloud Function for notifications

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External"
        direction TB
        Extern["External Clients (CLI/Web)"]:::external
    end

    subgraph "Self-Hosted Backend"
        direction TB
        LB["HTTP(S) Load Balancer"]:::compute
        subgraph "Django App Servers"
            direction TB
            APIApp["API App"]:::compute
            FSApp["Firestore App"]:::compute
        end
        Batch["Batch Job: upload_json_to_firestore.py"]:::batch
    end

    subgraph "GCP Project: uscheck-firestore"
        direction TB
        CB["GCS Bucket"]:::storage
        PS["Pub/Sub Topics"]:::messaging
        CF["Cloud Functions"]:::compute
        DB["Firestore (NoSQL DB)"]:::db
    end

    Extern -->|1 HTTP POST/GET| LB
    LB -->|2 Call REST Endpoints| APIApp
    APIApp -->|2 Uses Firestore SDK| DB
    Batch -->|3 Direct write via SDK| DB
    Extern -->|Client uploads JSON| CB
    CB -->|4 OBJECT_FINALIZE event| PS
    PS -->|5 Triggers| CF
    CF -->|6 Invoke ingestion endpoint| APIApp
    CF -->|6b Direct Firestore write| DB
    APIApp -->|7 Publish status message| PS

    click LB "https://github.com/us-check/server-firestore/tree/main/uscheck_firestore/uscheck_firestore/"
    click APIApp "https://github.com/us-check/server-firestore/tree/main/uscheck_firestore/api/"
    click FSApp "https://github.com/us-check/server-firestore/tree/main/uscheck_firestore/firestore/"
    click Batch "https://github.com/us-check/server-firestore/blob/main/uscheck_firestore/upload_json_to_firestore.py"

    classDef compute fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef storage fill:#E6FFED,stroke:#28a745,color:#28a745;
    classDef messaging fill:#FFF5D1,stroke:#dbab09,color:#dbab09;
    classDef db fill:#E0F7FA,stroke:#00acc1,color:#006064;
    classDef external fill:#F0F0F0,stroke:#666,color:#333,stroke-dasharray: 2 2;
    classDef batch fill:#FFEFEF,stroke:#d73a49,color:#d73a49;
```
