# azure-samples/react-cosmosdb architecture

> Architecture diagram of the GitHub repository azure-samples/react-cosmosdb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/react-cosmosdb
- Repository: https://github.com/azure-samples/react-cosmosdb

## Overview

##### Project type and purpose
- This is a full-stack demo application that pairs a React single-page app (SPA) with a Node/Express API server, persisting data in Azure CosmosDB via the MongoDB API.
- Its goal is to demonstrate how to perform CRUD operations from React to CosmosDB, debug both client and server, and deploy/scale on Azure.

##### File structure
- Top level
- public/ & src/ → Create React App front-end
- server/ → Express back-end, contains app.js, routes/, service & model layers, MongoDB client setup, view templates for errors, and environment config
- Dockerfile, package.json (root), server/package.json → build & runtime configs for both front-end and back-end
- Patterns
- SPA on the client
- On the server: MVC-ish layering (routes → service → model → database)
- Separate dev processes for React dev server and Express in development; unified server in production

##### README for additional insights
- Stack: React, Node.js/Express, Azure CosmosDB (Mongo API)
- Dev instructions: “node server/server.js” + “npm start” for CRA
- Prod instructions: build React app, then serve static assets from Express on port 3001
- Environment config lives in server/env/environment.js (renamed from environment-change-me.js)

a. Main components
- Client (Browser/React SPA)
- Development servers (React dev server & Express dev server)
- Production server (Express serving static React build)
- HeroService & HeroModel layers in Express
- Azure CosmosDB (Mongo API)
- Environment/config module
- Optional: Docker container wrapping the production server
b. Relationships and interactions
- Browser → HTTP(S) GET/POST/PUT/DELETE → Express API endpoints
- Express routes invoke HeroService → HeroModel → MongoDB client → CosmosDB
- In production: Express also serves React’s static JS/CSS from build/ or public/
- Configuration module injects connection parameters into MongoDB client
c. Architectural patterns & design principles
- Front-end/back-end separation (client-server architecture)
- SPA communicating via a RESTful API
- Server-side layering (routing → business logic → data access)
- Environment-driven config for portability (dev vs prod vs Docker)
d. Key technologies & frameworks
- React (Create React App)
- Node.js, Express, Jade (for error views)
- MongoDB Node.js driver configured for CosmosDB’s Mongo API
- Azure CosmosDB
- Docker (production image in Dockerfile)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (React SPA)"
        PublicIndex["public/index.html"]:::client
        Src["src/"]:::client
        APIClient["src/api.js"]:::client
    end
    click PublicIndex "https://github.com/azure-samples/react-cosmosdb/blob/master/public/index.html"
    click Src "https://github.com/azure-samples/react-cosmosdb/tree/master/src/"
    click APIClient "https://github.com/azure-samples/react-cosmosdb/blob/master/src/api.js"

    Browser["Browser (Running SPA)"]:::client
    Browser -->|"loads index.html"| PublicIndex
    Browser -->|"runs bundled JS"| Src

    Browser --> ReactDev
    ReactDev["React Dev Server (port 3000)"]:::client
    ReactDev -->|"API Requests"| ExpressDev
    ReactDev -->|"npm run build"| StaticFiles

    subgraph "Server (Express)"
        ServerJS["server/server.js"]:::server
        AppJS["server/app.js"]:::server
        Routes["server/routes/index.js"]:::server
        Service["server/hero-service.js"]:::server
        Model["server/hero-model.js"]:::server
        MongoClient["server/mongo.js"]:::server
        Env["server/env/environment-change-me.js"]:::config
        ErrorView["server/views/error.jade"]:::server
    end
    click ServerJS "https://github.com/azure-samples/react-cosmosdb/blob/master/server/server.js"
    click AppJS "https://github.com/azure-samples/react-cosmosdb/blob/master/server/app.js"
    click Routes "https://github.com/azure-samples/react-cosmosdb/blob/master/server/routes/index.js"
    click Service "https://github.com/azure-samples/react-cosmosdb/blob/master/server/hero-service.js"
    click Model "https://github.com/azure-samples/react-cosmosdb/blob/master/server/hero-model.js"
    click MongoClient "https://github.com/azure-samples/react-cosmosdb/blob/master/server/mongo.js"
    click Env "https://github.com/azure-samples/react-cosmosdb/blob/master/server/env/environment-change-me.js"
    click ErrorView "https://github.com/azure-samples/react-cosmosdb/blob/master/server/views/error.jade"

    ExpressDev["Express Dev Server (port 3001)"]:::server
    ReactDev --> ExpressDev
    ExpressDev --> ServerJS
    ServerJS --> AppJS
    AppJS --> Routes
    Routes --> Service
    Service --> Model
    Model --> MongoClient
    MongoClient --> CosmosDB
    Env --> MongoClient

    StaticFiles["Built React Static Files"]:::client
    ReactDev --> StaticFiles
    StaticFiles -->|served by| ServerJS

    subgraph "Production Deployment (Docker)"
        ProductionContainer["Docker Container"]:::server
        ProductionContainer --> StaticFiles
        ProductionContainer --> ServerJS
    end
    click Dockerfile "https://github.com/azure-samples/react-cosmosdb/tree/master/Dockerfile"

    subgraph "Configuration"
        RootPkg["package.json"]:::config
        ServerPkg["server/package.json"]:::config
    end
    click RootPkg "https://github.com/azure-samples/react-cosmosdb/blob/master/package.json"
    click ServerPkg "https://github.com/azure-samples/react-cosmosdb/blob/master/server/package.json"

    subgraph "Database"
        CosmosDB["Azure CosmosDB (Mongo API)"]:::external
    end

    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
