docs: architecture overview (#1230)

* docs: architecture overview

* fix

Author: danilowoz

website/docs/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.

website/docs/package.json

@@ -17,6 +17,8 @@
     "@radix-ui/react-tabs": "^1.0.1",
     "amplitude-js": "^8.13.0",
     "codesandbox-theme-docs": "^2.0.2",
+    "mdx-mermaid": "^2.0.2",
+    "mermaid": "^11.4.0",
     "next": "^14.0.0",
     "nextra": "^2.0.1",
     "nextra-theme-docs": "^2.0.1",

website/docs/src/pages/architecture/overview.mdx

@@ -0,0 +1,47 @@
+# Overview
+
+import { Mermaid } from 'mdx-mermaid/Mermaid';
+
+1. Sandpack React
+
+- `<Sandpack />` component initializes
+- Manages React integration & UI state
+
+2. Sandpack Clinet
+
+- `loadSandpackClient()` selects appropriate client type (VM/Runtime/Static/Node)
+- Creates sandbox context from files, template, and dependencies
+
+3. Bundler
+
+- Processes sandbox setup
+- Handles code bundling
+- Returns updates to client
+
+<br />
+
+<Mermaid chart={`
+sequenceDiagram
+    autonumber
+    participant R as Sandpack-react
+    participant C as Sandpack-client
+    
+    Note left of R: <Sandpack />
+    Note right of C: loadSandpackClient(...)
+    Note right of C: Depending on the template/env<br/>loadSandpackClient will return a<br />vm, runtime, static or node client
+    Note right of C: sandpack-client/clients/index.ts
+    R->>+C: Get sandbox context
+    Note over R,C: Based on files, template, and deps, <br/> will be create a SandpackContextInfo.
+    Note right of R: getSandpackStateFromProps(...)
+
+    C->>-R: New client instance
+    Note left of R: new SandpackClient()
+
+    create participant B as Bundler
+    C->>+B: Dispatch sandbox setup
+    B->>+C: Messages with updates
+    Note left of R: Once it's done, show <br/>iframe with preview
+    C->>-R: Done
+
+    C->>+R: Dispatch sandbox setup
+`} />

website/docs/src/pages/architecture/private-packages.mdx

@@ -0,0 +1,85 @@
+import { Mermaid } from 'mdx-mermaid/Mermaid';
+
+# Private dependencies: technical specification
+
+This document outlines the technical specification for enabling the use of private dependencies on CodeSandbox, specifically for Pro users. This feature leverages the existing infrastructure used for CodeSandbox's private package proxy to provide a secure and seamless experience for developers working with internal or private packages.
+
+### Use cases
+
+- **CodeSandbox proxy:** all secrets are stored on csb server, which will proxy internally and respond with package content. This is the safest way to deal with sensitive data once it doesn’t expose any secrets to the client;
+- **Companies with internal VPN**: given the nature of a VPN restriction, csb will respond with the registry token to the client, which then will fetch to the npm registry in the internal network.
+
+## Technical Specification
+
+1. Authentication Flow:
+- The Sandpack component initiates the authentication flow by redirecting the user to `codesandbox.io/auth/sandpack?team-id=<team-id>`.
+- The CodeSandbox authentication service verifies the team-id and provides a sandpack-secret token.
+- The sandpack-secret token is stored in a secure cookie with `SameSite=None` and `Secure=true` settings.
+
+2. Trusted Domains:
+- After the authentication flow, Sandpack requests the list of trusted domains for the specified team-id from the CodeSandbox API.
+- The API returns the list of trusted domains, which Sandpack uses to set the appropriate Content Security Policy (CSP) headers for the iframe.
+
+
+3. Package Fetch:
+- With the sandpack-secret token available, Sandpack makes requests to the CodeSandbox API to fetch the private package data.
+- The API authenticates the request using the sandpack-secret token and retrieves the package payload from the internal npm registry.
+- The API handles token renewal as necessary to ensure seamless access to the private package.
+
+<br />
+
+<Mermaid chart={`sequenceDiagram
+		participant U as mydomain.com
+    participant S as teamid.sandpack.codesandbox.io
+    participant C as codesandbox.io
+    participant A as API
+
+    Note over S: <Sandpack teamId="" />
+
+	  alt Pop-up authentication
+	    Note over U: 1st step
+	    S->>+C: Sign-in [team-id]
+	    C->>-A: GET /auth/sandpack [team-id]
+	    Note over A: website-url match team config?
+	    A->>+C: sandpack-token
+	    C->>-S: sandpack-token
+	    Note over S: Cookie SameSite=None Secure=true
+		end
+
+    Note over S: Refresh iframe to use the new cookie
+
+    alt Worker
+	    Note over U: 2nd step
+			U --> S: iframe src: teamid.sandpack.codesandbox.io
+			S ->>+A: GET /trusted-domains/:team-id
+			A ->>-S: List of trusted domains 
+			S ->> U: CSP: frame-ancestors
+		end
+
+    Note over U: At this point, this domain is a trusted one
+
+    alt Authenticated connection 
+		    Note over U: 3rd step: run sandbox
+        U->>+S: Run this sandbox
+        S->>+A: GET /[team-id]/npm_registry
+				A->>-S: Registry configuration
+        S->>+A: GET /[team-id]/npm_registry/[package]
+		    Note over A: Make sure it renews the token as need
+        A->>-S: Package payload
+    end`} />
+
+### Worker Technical Specification
+
+<br />
+
+<Mermaid chart={`
+sequenceDiagram
+		participant U as mydomain.com
+    participant S as teamid-2-0-0-sandpack.codesandbox.io
+    participant A as API
+
+		U --> S: iframe src: teamid.sandpack.codesandbox.io
+		S ->>+A: GET /trusted-domains/:team-id
+		A ->>-S: List of trusted domains 
+		S ->> U: CSP: frame-ancestors
+`} />