# rohan-shridhar/gridcraft architecture

> Architecture diagram of the GitHub repository rohan-shridhar/gridcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohan-shridhar/gridcraft
- Repository: https://github.com/rohan-shridhar/gridcraft

## Overview

GridCraft is a browser-based art and collaboration workspace whose artwork library lives in each creator’s GitHub repository. The main workflow is GitHub sign-in, album browsing, canvas editing and saving, with Stories, branch workflows, forks, and GridCraft-native Issues and Pull Requests as distinct capabilities. The frontend calls an Express API; backend controllers coordinate domain services, which use GitHub for artwork-library operations. The README documents capabilities beyond the sampled implementation, so those branches are included while uncertain internal links are omitted.

Main entry points: [`server/src/routes/albumRoutes.js`](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/routes/albumRoutes.js) (Album routes), [`server/src/controllers/authController.js`](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/authController.js) (OAuth API), [`src/App.jsx`](https://github.com/rohan-shridhar/gridcraft/blob/main/src/App.jsx) (Workspace shell), [`src/components/ArtworkEditor.jsx`](https://github.com/rohan-shridhar/gridcraft/blob/main/src/components/ArtworkEditor.jsx) (Artwork editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace frontend"]
  node_app["Workspace shell<br/>[App.jsx]"]
  node_auth_ui["Auth state<br/>[useAuth.jsx]"]
  node_api_client["API client<br/>[apiClient.js]"]
  node_album_ui["Album workspace<br/>[AlbumDetail.jsx]"]
  node_editor["Artwork editor<br/>[ArtworkEditor.jsx]"]
  node_canvas_tools["Canvas controls<br/>[Tools.jsx]"]
  node_canvas_grid["Drawing grid<br/>[Grid.jsx]"]
end

subgraph group_identity["Authentication"]
  node_auth_api["OAuth API<br/>[authController.js]"]
  node_auth_service["GitHub auth service"]
  node_session_middleware["Session middleware<br/>[auth.js]"]
  node_session_crypto["Session cryptography<br/>[crypto.js]"]
end

subgraph group_library["Artwork library"]
  node_album_api["Album API<br/>[albumController.js]"]
  node_artwork_api["Artwork API"]
  node_story_api["Story API<br/>[storyController.js]"]
  node_branch_api["Branch API"]
  node_album_service["Album service<br/>[albumService.js]"]
  node_artwork_service["Artwork service<br/>[artworkService.js]"]
  node_story_service["Story service<br/>[storyService.js]"]
  node_branch_service["Branch service<br/>[branchService.js]"]
end

subgraph group_collaboration["Collaboration"]
  node_issues_api["Issues API<br/>[issueController.js]"]
  node_issues_service["Issues service<br/>[issueService.js]"]
  node_pulls_api["Pull requests API"]
  node_pulls_service["Pull requests service"]
  node_fork_api["Album fork API<br/>[forkController.js]"]
  node_fork_service["Album fork service<br/>[forkService.js]"]
end

subgraph group_backend["API runtime"]
  node_http_app["Express API<br/>[app.js]"]
  node_routes["Album routes<br/>[albumRoutes.js]"]
  node_github_client["GitHub client<br/>[githubClient.js]"]
  node_runtime_config["Runtime configuration<br/>[env.js]"]
end

node_creator(("Creator"))
node_library_repo[("GitHub artwork library")]
node_github_api["GitHub API"]

node_creator -->|"uses"| node_app
node_app -->|"checks identity"| node_auth_ui
node_auth_ui -->|"requests session"| node_api_client
node_app -->|"shows album"| node_album_ui
node_album_ui -->|"loads album data"| node_api_client
node_app -->|"opens artwork"| node_editor
node_editor -->|"renders controls"| node_canvas_tools
node_editor -->|"renders canvas"| node_canvas_grid
node_editor -->|"saves artwork"| node_api_client
node_api_client -.->|"sends API requests"| node_http_app
node_http_app -->|"configures runtime"| node_runtime_config
node_http_app -->|"mounts routes"| node_routes
node_routes -->|"dispatches albums"| node_album_api
node_routes -->|"dispatches artwork"| node_artwork_api
node_routes -->|"dispatches stories"| node_story_api
node_routes -->|"dispatches branches"| node_branch_api
node_routes -->|"dispatches issues"| node_issues_api
node_routes -->|"dispatches pull requests"| node_pulls_api
node_routes -->|"dispatches forks"| node_fork_api
node_album_api -->|"delegates album operations"| node_album_service
node_artwork_api -->|"delegates artwork operations"| node_artwork_service
node_story_api -->|"delegates story operations"| node_story_service
node_branch_api -->|"delegates branch operations"| node_branch_service
node_issues_api -->|"delegates issue operations"| node_issues_service
node_pulls_api -->|"delegates pull requests"| node_pulls_service
node_fork_api -->|"delegates forks"| node_fork_service
node_album_service -->|"makes GitHub requests"| node_github_client
node_github_client -->|"calls GitHub"| node_github_api
node_github_api -->|"reads and writes library"| node_library_repo
node_auth_api -->|"exchanges OAuth code"| node_auth_service
node_auth_api -->|"initializes library"| node_album_service
node_auth_api -->|"encrypts session token"| node_session_crypto
node_session_middleware -->|"verifies and decrypts"| node_session_crypto
node_auth_api -.->|"performs GitHub OAuth"| node_github_api

click node_app "https://github.com/rohan-shridhar/gridcraft/blob/main/src/App.jsx"
click node_auth_ui "https://github.com/rohan-shridhar/gridcraft/blob/main/src/hooks/useAuth.jsx"
click node_api_client "https://github.com/rohan-shridhar/gridcraft/blob/main/src/services/apiClient.js"
click node_album_ui "https://github.com/rohan-shridhar/gridcraft/blob/main/src/components/AlbumDetail.jsx"
click node_editor "https://github.com/rohan-shridhar/gridcraft/blob/main/src/components/ArtworkEditor.jsx"
click node_canvas_tools "https://github.com/rohan-shridhar/gridcraft/blob/main/src/Tools.jsx"
click node_canvas_grid "https://github.com/rohan-shridhar/gridcraft/blob/main/src/Grid.jsx"
click node_album_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/albumController.js"
click node_artwork_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/artworkController.js"
click node_story_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/storyController.js"
click node_branch_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/branchController.js"
click node_album_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/albumService.js"
click node_artwork_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/artworkService.js"
click node_story_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/storyService.js"
click node_branch_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/branchService.js"
click node_auth_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/authController.js"
click node_auth_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/githubAuthService.js"
click node_session_middleware "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/middleware/auth.js"
click node_session_crypto "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/utils/crypto.js"
click node_issues_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/issueController.js"
click node_issues_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/issueService.js"
click node_pulls_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/pullRequestController.js"
click node_pulls_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/pullRequestService.js"
click node_fork_api "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/forkController.js"
click node_fork_service "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/forkService.js"
click node_http_app "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/app.js"
click node_routes "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/routes/albumRoutes.js"
click node_github_client "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/utils/githubClient.js"
click node_runtime_config "https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/config/env.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_auth_ui,node_api_client,node_album_ui,node_editor,node_canvas_tools,node_canvas_grid toneBlue
class node_auth_api,node_auth_service,node_session_middleware,node_session_crypto,node_library_repo toneAmber
class node_album_api,node_artwork_api,node_story_api,node_branch_api,node_album_service,node_artwork_service,node_story_service,node_branch_service,node_github_api toneMint
class node_issues_api,node_issues_service,node_pulls_api,node_pulls_service,node_fork_api,node_fork_service toneRose
class node_http_app,node_routes,node_github_client,node_runtime_config,node_creator toneIndigo
```

## Components

### Workspace frontend

- [Workspace shell](https://github.com/rohan-shridhar/gridcraft/blob/main/src/App.jsx): `src/App.jsx`
- [Auth state](https://github.com/rohan-shridhar/gridcraft/blob/main/src/hooks/useAuth.jsx): `src/hooks/useAuth.jsx`
- [API client](https://github.com/rohan-shridhar/gridcraft/blob/main/src/services/apiClient.js): `src/services/apiClient.js`
- [Album workspace](https://github.com/rohan-shridhar/gridcraft/blob/main/src/components/AlbumDetail.jsx): `src/components/AlbumDetail.jsx`
- [Artwork editor](https://github.com/rohan-shridhar/gridcraft/blob/main/src/components/ArtworkEditor.jsx): `src/components/ArtworkEditor.jsx`
- [Canvas controls](https://github.com/rohan-shridhar/gridcraft/blob/main/src/Tools.jsx): `src/Tools.jsx`
- [Drawing grid](https://github.com/rohan-shridhar/gridcraft/blob/main/src/Grid.jsx): `src/Grid.jsx`

### Authentication

- [OAuth API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/authController.js): `server/src/controllers/authController.js`
- [GitHub auth service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/githubAuthService.js): `server/src/services/githubAuthService.js`
- [Session middleware](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`
- [Session cryptography](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/utils/crypto.js): `server/src/utils/crypto.js`

### Artwork library

- [Album API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/albumController.js): `server/src/controllers/albumController.js`
- [Artwork API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/artworkController.js): `server/src/controllers/artworkController.js`
- [Story API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/storyController.js): `server/src/controllers/storyController.js`
- [Branch API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/branchController.js): `server/src/controllers/branchController.js`
- [Album service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/albumService.js): `server/src/services/albumService.js`
- [Artwork service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/artworkService.js): `server/src/services/artworkService.js`
- [Story service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/storyService.js): `server/src/services/storyService.js`
- [Branch service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/branchService.js): `server/src/services/branchService.js`

### Collaboration

- [Issues API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/issueController.js): `server/src/controllers/issueController.js`
- [Issues service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/issueService.js): `server/src/services/issueService.js`
- [Pull requests API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/pullRequestController.js): `server/src/controllers/pullRequestController.js`
- [Pull requests service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/pullRequestService.js): `server/src/services/pullRequestService.js`
- [Album fork API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/controllers/forkController.js): `server/src/controllers/forkController.js`
- [Album fork service](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/services/forkService.js): `server/src/services/forkService.js`

### API runtime

- [Express API](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/app.js): `server/src/app.js`
- [Album routes](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/routes/albumRoutes.js): `server/src/routes/albumRoutes.js`
- [GitHub client](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/utils/githubClient.js): `server/src/utils/githubClient.js`
- [Runtime configuration](https://github.com/rohan-shridhar/gridcraft/blob/main/server/src/config/env.js): `server/src/config/env.js`

### Other components

- **Creator**
- **GitHub artwork library**
- **GitHub API**

## Connections

- Creator → Workspace shell: uses (evidence: `README.md`)
- Workspace shell → Auth state: checks identity (evidence: `src/App.jsx`)
- Auth state → API client: requests session (evidence: `src/hooks/useAuth.jsx`)
- Workspace shell → Album workspace: shows album (evidence: `src/App.jsx`)
- Album workspace → API client: loads album data (evidence: `src/components/AlbumDetail.jsx`)
- Workspace shell → Artwork editor: opens artwork (evidence: `src/App.jsx`)
- Artwork editor → Canvas controls: renders controls (evidence: `src/components/ArtworkEditor.jsx`)
- Artwork editor → Drawing grid: renders canvas (evidence: `src/components/ArtworkEditor.jsx`)
- Artwork editor → API client: saves artwork (evidence: `src/components/ArtworkEditor.jsx`)
- API client → Express API: sends API requests
- Express API → Runtime configuration: configures runtime (evidence: `server/src/app.js`)
- Express API → Album routes: mounts routes (evidence: `server/src/app.js`)
- Album routes → Album API: dispatches albums (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Artwork API: dispatches artwork (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Story API: dispatches stories (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Branch API: dispatches branches (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Issues API: dispatches issues (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Pull requests API: dispatches pull requests (evidence: `server/src/routes/albumRoutes.js`)
- Album routes → Album fork API: dispatches forks (evidence: `server/src/routes/albumRoutes.js`)
- Album API → Album service: delegates album operations (evidence: `server/src/controllers/albumController.js`)
- Artwork API → Artwork service: delegates artwork operations (evidence: `server/src/controllers/artworkController.js`)
- Story API → Story service: delegates story operations (evidence: `server/src/controllers/storyController.js`)
- Branch API → Branch service: delegates branch operations (evidence: `server/src/controllers/branchController.js`)
- Issues API → Issues service: delegates issue operations (evidence: `server/src/controllers/issueController.js`)
- Pull requests API → Pull requests service: delegates pull requests (evidence: `server/src/controllers/pullRequestController.js`)
- Album fork API → Album fork service: delegates forks (evidence: `server/src/controllers/forkController.js`)
- Album service → GitHub client: makes GitHub requests (evidence: `server/src/services/albumService.js`)
- GitHub client → GitHub API: calls GitHub (evidence: `server/src/utils/githubClient.js`)
- GitHub API → GitHub artwork library: reads and writes library (evidence: `README.md`)
- OAuth API → GitHub auth service: exchanges OAuth code (evidence: `server/src/controllers/authController.js`)
- OAuth API → Album service: initializes library (evidence: `server/src/controllers/authController.js`)
- OAuth API → Session cryptography: encrypts session token (evidence: `server/src/controllers/authController.js`)
- Session middleware → Session cryptography: verifies and decrypts (evidence: `server/src/middleware/auth.js`)
- OAuth API → GitHub API: performs GitHub OAuth
