# kannan637/moodbaord architecture

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

- Interactive diagram: https://gitdiagram.com/kannan637/moodbaord
- Repository: https://github.com/kannan637/moodbaord

## Overview

Moodboard captures inspiration into user-owned boards: users authenticate, create/select a board, then import images from the Chrome extension or drop files onto the web canvas; images are processed and stored, while canvas elements and image placement remain editable. The backend separates API routing, domain services, MongoDB documents, and local image files. The README documents the Next.js app and extension flows, but no frontend source files appear in the supplied tree, so frontend internals and its API wiring are not verified.

Main entry points: [`backend/app/main.py`](https://github.com/kannan637/moodbaord/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/images.py`](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/images.py) (Image routes), [`backend/app/services/image_service.py`](https://github.com/kannan637/moodbaord/blob/main/backend/app/services/image_service.py) (Image ingestion and editing), [`backend/app/database.py`](https://github.com/kannan637/moodbaord/blob/main/backend/app/database.py) (MongoDB documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture clients"]
  node_onboarding["Extension onboarding<br/>[onboarding.js]"]
  node_page_capture["Page image capture<br/>[content.js]"]
  node_extension_bg["Extension background<br/>[background.js]"]
  node_web_app["Web canvas app"]
end

subgraph group_api["Backend API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_board_routes["Board routes<br/>[boards.py]"]
  node_image_routes["Image routes<br/>[images.py]"]
  node_element_routes["Canvas element routes<br/>[canvas_elements.py]"]
  node_auth_deps["User authentication dependency<br/>[deps.py]"]
end

subgraph group_domain["Domain services"]
  node_auth_service["Clerk token service<br/>[auth_service.py]"]
  node_board_service["Board management<br/>[board_service.py]"]
  node_image_service["Image ingestion and editing<br/>[image_service.py]"]
  node_element_service["Canvas element management"]
  node_url_safety["URL safety checks<br/>[url_safety.py]"]
end

subgraph group_state["Persistence and files"]
  node_mongo[("MongoDB documents<br/>[database.py]")]
  node_user_model["User records<br/>[user.py]"]
  node_board_model["Board records<br/>[board.py]"]
  node_image_model["Image records<br/>[image.py]"]
  node_element_model["Canvas element records<br/>[canvas_element.py]"]
  node_local_storage[("Local image files<br/>[config.py]")]
end

node_designer(("Designer"))
node_clerk["Clerk identity"]
node_source_sites["Image source sites"]

node_designer -->|"signs in"| node_onboarding
node_designer -->|"selects images"| node_page_capture
node_source_sites -->|"provides images"| node_page_capture
node_page_capture -.->|"sends capture"| node_extension_bg
node_extension_bg -->|"imports images"| node_image_routes
node_designer -->|"drops image"| node_web_app
node_web_app -.->|"submits upload"| node_image_routes
node_api_app -->|"registers router"| node_auth_routes
node_api_app -->|"registers router"| node_board_routes
node_api_app -->|"registers router"| node_image_routes
node_api_app -->|"registers router"| node_element_routes
node_api_app -->|"initializes database"| node_mongo
node_auth_routes -->|"uses dependency"| node_auth_deps
node_board_routes -->|"uses dependency"| node_auth_deps
node_image_routes -->|"uses dependency"| node_auth_deps
node_element_routes -->|"uses dependency"| node_auth_deps
node_auth_deps -->|"validates token"| node_auth_service
node_auth_service -->|"fetches signing keys"| node_clerk
node_auth_service -->|"looks up or creates"| node_user_model
node_board_routes -->|"delegates board work"| node_board_service
node_image_routes -->|"delegates image work"| node_image_service
node_image_routes -->|"checks board access"| node_board_service
node_element_routes -->|"delegates element work"| node_element_service
node_board_service -->|"reads and writes"| node_board_model
node_board_service -->|"queries images"| node_image_model
node_board_service -->|"deletes elements"| node_element_model
node_image_service -->|"stores image state"| node_image_model
node_image_service -->|"checks ownership"| node_board_model
node_image_service -->|"validates source URL"| node_url_safety
node_image_service -->|"writes processed files"| node_local_storage
node_element_service -->|"reads and writes"| node_element_model
node_element_service -->|"checks board ownership"| node_board_model
node_api_app -->|"serves static images"| node_local_storage
node_mongo -->|"registers model"| node_user_model
node_mongo -->|"registers model"| node_board_model
node_mongo -->|"registers model"| node_image_model
node_mongo -->|"registers model"| node_element_model

click node_onboarding "https://github.com/kannan637/moodbaord/blob/main/extension/onboarding/onboarding.js"
click node_page_capture "https://github.com/kannan637/moodbaord/blob/main/extension/content.js"
click node_extension_bg "https://github.com/kannan637/moodbaord/blob/main/extension/background.js"
click node_web_app "https://github.com/kannan637/moodbaord/tree/main/frontend"
click node_api_app "https://github.com/kannan637/moodbaord/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/kannan637/moodbaord/blob/main/backend/app/api/auth.py"
click node_board_routes "https://github.com/kannan637/moodbaord/blob/main/backend/app/api/boards.py"
click node_image_routes "https://github.com/kannan637/moodbaord/blob/main/backend/app/api/images.py"
click node_element_routes "https://github.com/kannan637/moodbaord/blob/main/backend/app/api/canvas_elements.py"
click node_auth_deps "https://github.com/kannan637/moodbaord/blob/main/backend/app/api/deps.py"
click node_auth_service "https://github.com/kannan637/moodbaord/blob/main/backend/app/services/auth_service.py"
click node_board_service "https://github.com/kannan637/moodbaord/blob/main/backend/app/services/board_service.py"
click node_image_service "https://github.com/kannan637/moodbaord/blob/main/backend/app/services/image_service.py"
click node_element_service "https://github.com/kannan637/moodbaord/blob/main/backend/app/services/canvas_element_service.py"
click node_url_safety "https://github.com/kannan637/moodbaord/blob/main/backend/app/utils/url_safety.py"
click node_mongo "https://github.com/kannan637/moodbaord/blob/main/backend/app/database.py"
click node_user_model "https://github.com/kannan637/moodbaord/blob/main/backend/app/models/user.py"
click node_board_model "https://github.com/kannan637/moodbaord/blob/main/backend/app/models/board.py"
click node_image_model "https://github.com/kannan637/moodbaord/blob/main/backend/app/models/image.py"
click node_element_model "https://github.com/kannan637/moodbaord/blob/main/backend/app/models/canvas_element.py"
click node_local_storage "https://github.com/kannan637/moodbaord/blob/main/backend/app/config.py"

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_onboarding,node_page_capture,node_extension_bg,node_web_app toneBlue
class node_api_app,node_auth_routes,node_board_routes,node_image_routes,node_element_routes,node_auth_deps toneAmber
class node_auth_service,node_board_service,node_image_service,node_element_service,node_url_safety toneMint
class node_mongo,node_user_model,node_board_model,node_image_model,node_element_model,node_local_storage toneRose
class node_designer,node_clerk,node_source_sites toneIndigo
```

## Components

### Capture clients

- [Extension onboarding](https://github.com/kannan637/moodbaord/blob/main/extension/onboarding/onboarding.js): `extension/onboarding/onboarding.js`
- [Page image capture](https://github.com/kannan637/moodbaord/blob/main/extension/content.js): `extension/content.js`
- [Extension background](https://github.com/kannan637/moodbaord/blob/main/extension/background.js): `extension/background.js`
- [Web canvas app](https://github.com/kannan637/moodbaord/tree/main/frontend): `frontend`

### Backend API

- [FastAPI application](https://github.com/kannan637/moodbaord/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Board routes](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/boards.py): `backend/app/api/boards.py`
- [Image routes](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/images.py): `backend/app/api/images.py`
- [Canvas element routes](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/canvas_elements.py): `backend/app/api/canvas_elements.py`
- [User authentication dependency](https://github.com/kannan637/moodbaord/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Domain services

- [Clerk token service](https://github.com/kannan637/moodbaord/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Board management](https://github.com/kannan637/moodbaord/blob/main/backend/app/services/board_service.py): `backend/app/services/board_service.py`
- [Image ingestion and editing](https://github.com/kannan637/moodbaord/blob/main/backend/app/services/image_service.py): `backend/app/services/image_service.py`
- [Canvas element management](https://github.com/kannan637/moodbaord/blob/main/backend/app/services/canvas_element_service.py): `backend/app/services/canvas_element_service.py`
- [URL safety checks](https://github.com/kannan637/moodbaord/blob/main/backend/app/utils/url_safety.py): `backend/app/utils/url_safety.py`

### Persistence and files

- [MongoDB documents](https://github.com/kannan637/moodbaord/blob/main/backend/app/database.py): `backend/app/database.py`
- [User records](https://github.com/kannan637/moodbaord/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Board records](https://github.com/kannan637/moodbaord/blob/main/backend/app/models/board.py): `backend/app/models/board.py`
- [Image records](https://github.com/kannan637/moodbaord/blob/main/backend/app/models/image.py): `backend/app/models/image.py`
- [Canvas element records](https://github.com/kannan637/moodbaord/blob/main/backend/app/models/canvas_element.py): `backend/app/models/canvas_element.py`
- [Local image files](https://github.com/kannan637/moodbaord/blob/main/backend/app/config.py): `backend/app/config.py`

### Other components

- **Designer**
- **Clerk identity**
- **Image source sites**

## Connections

- Designer → Extension onboarding: signs in (evidence: `README.md`)
- Designer → Page image capture: selects images (evidence: `README.md`)
- Image source sites → Page image capture: provides images (evidence: `README.md`)
- Page image capture → Extension background: sends capture
- Extension background → Image routes: imports images (evidence: `README.md`)
- Designer → Web canvas app: drops image (evidence: `README.md`)
- Web canvas app → Image routes: submits upload
- FastAPI application → Auth routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Board routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Image routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Canvas element routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → MongoDB documents: initializes database (evidence: `backend/app/main.py`)
- Auth routes → User authentication dependency: uses dependency (evidence: `backend/app/api/auth.py`)
- Board routes → User authentication dependency: uses dependency (evidence: `backend/app/api/boards.py`)
- Image routes → User authentication dependency: uses dependency (evidence: `backend/app/api/images.py`)
- Canvas element routes → User authentication dependency: uses dependency (evidence: `backend/app/api/canvas_elements.py`)
- User authentication dependency → Clerk token service: validates token (evidence: `backend/app/api/deps.py`)
- Clerk token service → Clerk identity: fetches signing keys (evidence: `backend/app/services/auth_service.py`)
- Clerk token service → User records: looks up or creates (evidence: `backend/app/services/auth_service.py`)
- Board routes → Board management: delegates board work (evidence: `backend/app/api/boards.py`)
- Image routes → Image ingestion and editing: delegates image work (evidence: `backend/app/api/images.py`)
- Image routes → Board management: checks board access (evidence: `backend/app/api/images.py`)
- Canvas element routes → Canvas element management: delegates element work (evidence: `backend/app/api/canvas_elements.py`)
- Board management → Board records: reads and writes (evidence: `backend/app/services/board_service.py`)
- Board management → Image records: queries images (evidence: `backend/app/services/board_service.py`)
- Board management → Canvas element records: deletes elements (evidence: `backend/app/services/board_service.py`)
- Image ingestion and editing → Image records: stores image state (evidence: `backend/app/services/image_service.py`)
- Image ingestion and editing → Board records: checks ownership (evidence: `backend/app/services/image_service.py`)
- Image ingestion and editing → URL safety checks: validates source URL (evidence: `backend/app/services/image_service.py`)
- Image ingestion and editing → Local image files: writes processed files (evidence: `backend/app/services/image_service.py`)
- Canvas element management → Canvas element records: reads and writes (evidence: `backend/app/services/canvas_element_service.py`)
- Canvas element management → Board records: checks board ownership (evidence: `backend/app/services/canvas_element_service.py`)
- FastAPI application → Local image files: serves static images (evidence: `backend/app/main.py`)
- MongoDB documents → User records: registers model (evidence: `backend/app/database.py`)
- MongoDB documents → Board records: registers model (evidence: `backend/app/database.py`)
- MongoDB documents → Image records: registers model (evidence: `backend/app/database.py`)
- MongoDB documents → Canvas element records: registers model (evidence: `backend/app/database.py`)
