# System Architecture

Rockhopper is a cloud-hosted SaaS platform that integrates with Microsoft 365 and Google Workspace to provide version control and collaboration for spreadsheets. The system is designed with security isolation, least-privilege access, and defense in depth.

## Platform components

| Component                    | Purpose                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| **Web application**          | Browser-based interface for managing files, viewing change diffs, commenting, and reviewing |
| **Excel add-in**             | Runs within Microsoft Excel (desktop and web) to track changes in real time                 |
| **Google Sheets sidebar**    | Runs within Google Sheets to track changes in real time                                     |
| **API server**               | Processes all business logic, authentication, authorization, and data operations            |
| **Background job processor** | Handles change attribution and file synchronization asynchronously                          |
| **Database**                 | Stores user accounts, file metadata, version history, comments, and review records          |
| **Object storage**           | Stores spreadsheet version snapshots                                                        |
| **Real-time server**         | WebSocket server for live updates between concurrent users                                  |

## Cloud infrastructure

All infrastructure is hosted on **Amazon Web Services (AWS)**:

* Compute, networking, and storage are managed entirely within AWS
* Production and staging environments are isolated in separate VPCs with no cross-environment access
* Database clusters run in high-availability configurations with automatic failover
* Object storage uses S3 with 99.999999999% (11 nines) durability for version snapshots
* Secrets and credentials are managed via AWS Secrets Manager with KMS encryption

![Rockhopper cloud architecture diagram showing test and production environments on AWS](/files/qQzTtihQgXICojCoF32m)

## Integration approach

### Microsoft 365

Rockhopper connects to Microsoft 365 tenants via **Microsoft Entra ID** (Azure AD):

* Users authenticate via industry-standard OAuth 2.0 / OpenID Connect
* File access uses the Microsoft Graph API with delegated permissions scoped to the signed-in user
* Only the minimum required permissions are requested (see [Microsoft Permissions](/security-and-compliance/microsoft-permissions.md))
* No Microsoft credentials are stored — authentication tokens are held in memory only

### Google Workspace

Rockhopper connects to Google Workspace via **Google Identity**:

* Users authenticate via Google OAuth 2.0
* File access uses the Google Drive and Sheets APIs with delegated permissions
* Refresh tokens are encrypted and stored securely in the database

## Data flow

When a user edits an enrolled spreadsheet:

1. The add-in or sidebar detects the change via platform APIs (Office.js or Google Apps Script)
2. The change event is reported to the Rockhopper API server
3. The backend records the change and runs a background job to attribute it to the specific user
4. Attributed changes appear in the web application's change log and diff view
5. When the user creates a new version, the backend downloads the current file, stores a snapshot, and mints a semantic version number


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rockhopper.co/security-and-compliance/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.