# coppsary/motify-backend architecture

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

- Interactive diagram: https://gitdiagram.com/coppsary/motify-backend
- Repository: https://github.com/coppsary/motify-backend

## Overview

Motify Backend is an optional hosted API for Motify’s source-based editor. The main request path is the editor calling the Express server, which routes authenticated requests through controllers into services and persistence; project saves preserve authored source rather than introducing another animation format. Distinct capabilities include account and workspace management, projects, assets and audio, brand data, AI-assisted generation, and credits and payments. The README describes rendering as an intended separate worker capability, but no renderer appears in the supplied tree. Some subsystem links rely on the source index or README rather than sampled implementation details.

Main entry points: [`src/server.ts`](https://github.com/coppsary/motify-backend/blob/main/src/server.ts) (API server), [`src/services/payment.service.ts`](https://github.com/coppsary/motify-backend/blob/main/src/services/payment.service.ts) (Payment service), [`packages/database/schema.ts`](https://github.com/coppsary/motify-backend/blob/main/packages/database/schema.ts) (PostgreSQL schema), [`src/repositories/auth.repository.ts`](https://github.com/coppsary/motify-backend/blob/main/src/repositories/auth.repository.ts) (Auth persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["API server<br/>[server.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_authcontroller["Auth controller<br/>[auth.controller.ts]"]
  node_authentication["Session middleware<br/>[authentication.ts]"]
end

subgraph group_accounts["Identity and Workspaces"]
  node_authservice["Auth service<br/>[auth.service.ts]"]
  node_authrepo["Auth persistence<br/>[auth.repository.ts]"]
  node_provider["Supabase Auth"]
  node_workspace["Workspace service"]
end

subgraph group_creative["Creative Workflows"]
  node_projectcontroller["Project controller"]
  node_projectservice["Project service<br/>[project.service.ts]"]
  node_generation["AI generation agent<br/>[motify-agent.ts]"]
  node_motiongraph["Generation records"]
end

subgraph group_resources["Assets and Audio"]
  node_assetcontroller["Asset controller"]
  node_assetservice["Asset service<br/>[asset.service.ts]"]
  node_storage["Object storage"]
  node_audio["Audio catalog<br/>[audio.service.ts]"]
end

subgraph group_commerce["Billing and Persistence"]
  node_payment["Payment service<br/>[payment.service.ts]"]
  node_bakong["Bakong API client<br/>[client.ts]"]
  node_database[("PostgreSQL schema<br/>[schema.ts]")]
end

node_editor(("Motify editor"))

node_editor -->|"calls API"| node_server
node_server -->|"mounts routes"| node_authroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_server -->|"resolves sessions"| node_authentication
node_authcontroller -->|"invokes"| node_authservice
node_authrepo -->|"reads and writes"| node_database
node_authrepo -->|"uses provider types"| node_provider
node_server -->|"configures"| node_projectcontroller
node_projectcontroller -->|"invokes"| node_projectservice
node_server -->|"configures agent"| node_generation
node_motiongraph -->|"uses generation schemas"| node_generation
node_server -->|"mounts asset routes"| node_assetcontroller
node_assetcontroller -->|"invokes"| node_assetservice
node_assetservice -->|"uses storage adapter"| node_storage
node_audio -->|"persists catalog"| node_database
node_server -->|"configures service"| node_payment
node_payment -->|"checks payments"| node_bakong
node_payment -->|"uses workspace service"| node_workspace
node_server -->|"creates database"| node_database

click node_server "https://github.com/coppsary/motify-backend/blob/main/src/server.ts"
click node_authroutes "https://github.com/coppsary/motify-backend/blob/main/src/routes/auth.routes.ts"
click node_authcontroller "https://github.com/coppsary/motify-backend/blob/main/src/controllers/auth.controller.ts"
click node_authentication "https://github.com/coppsary/motify-backend/blob/main/src/middleware/authentication.ts"
click node_authservice "https://github.com/coppsary/motify-backend/blob/main/src/services/auth.service.ts"
click node_authrepo "https://github.com/coppsary/motify-backend/blob/main/src/repositories/auth.repository.ts"
click node_provider "https://github.com/coppsary/motify-backend/blob/main/packages/auth/supabase-provider.ts"
click node_workspace "https://github.com/coppsary/motify-backend/blob/main/src/services/workspace.service.ts"
click node_projectcontroller "https://github.com/coppsary/motify-backend/blob/main/src/controllers/project.controller.ts"
click node_projectservice "https://github.com/coppsary/motify-backend/blob/main/src/services/project.service.ts"
click node_generation "https://github.com/coppsary/motify-backend/blob/main/packages/ai/agent/motify-agent.ts"
click node_motiongraph "https://github.com/coppsary/motify-backend/blob/main/src/repositories/motion-graph.repository.ts"
click node_assetcontroller "https://github.com/coppsary/motify-backend/blob/main/src/controllers/asset.controller.ts"
click node_assetservice "https://github.com/coppsary/motify-backend/blob/main/src/services/asset.service.ts"
click node_storage "https://github.com/coppsary/motify-backend/blob/main/packages/object-storage/supabase-storage.ts"
click node_audio "https://github.com/coppsary/motify-backend/blob/main/src/services/audio.service.ts"
click node_payment "https://github.com/coppsary/motify-backend/blob/main/src/services/payment.service.ts"
click node_bakong "https://github.com/coppsary/motify-backend/blob/main/packages/bakong/client.ts"
click node_database "https://github.com/coppsary/motify-backend/blob/main/packages/database/schema.ts"

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_server,node_authroutes,node_authcontroller,node_authentication toneBlue
class node_authservice,node_authrepo,node_provider,node_workspace toneAmber
class node_projectcontroller,node_projectservice,node_generation,node_motiongraph toneMint
class node_assetcontroller,node_assetservice,node_storage,node_audio toneRose
class node_payment,node_bakong,node_database,node_editor toneIndigo
```

## Components

### HTTP API

- [API server](https://github.com/coppsary/motify-backend/blob/main/src/server.ts): `src/server.ts`
- [Auth routes](https://github.com/coppsary/motify-backend/blob/main/src/routes/auth.routes.ts): `src/routes/auth.routes.ts`
- [Auth controller](https://github.com/coppsary/motify-backend/blob/main/src/controllers/auth.controller.ts): `src/controllers/auth.controller.ts`
- [Session middleware](https://github.com/coppsary/motify-backend/blob/main/src/middleware/authentication.ts): `src/middleware/authentication.ts`

### Identity and Workspaces

- [Auth service](https://github.com/coppsary/motify-backend/blob/main/src/services/auth.service.ts): `src/services/auth.service.ts`
- [Auth persistence](https://github.com/coppsary/motify-backend/blob/main/src/repositories/auth.repository.ts): `src/repositories/auth.repository.ts`
- [Supabase Auth](https://github.com/coppsary/motify-backend/blob/main/packages/auth/supabase-provider.ts): `packages/auth/supabase-provider.ts`
- [Workspace service](https://github.com/coppsary/motify-backend/blob/main/src/services/workspace.service.ts): `src/services/workspace.service.ts`

### Creative Workflows

- [Project controller](https://github.com/coppsary/motify-backend/blob/main/src/controllers/project.controller.ts): `src/controllers/project.controller.ts`
- [Project service](https://github.com/coppsary/motify-backend/blob/main/src/services/project.service.ts): `src/services/project.service.ts`
- [AI generation agent](https://github.com/coppsary/motify-backend/blob/main/packages/ai/agent/motify-agent.ts): `packages/ai/agent/motify-agent.ts`
- [Generation records](https://github.com/coppsary/motify-backend/blob/main/src/repositories/motion-graph.repository.ts): `src/repositories/motion-graph.repository.ts`

### Assets and Audio

- [Asset controller](https://github.com/coppsary/motify-backend/blob/main/src/controllers/asset.controller.ts): `src/controllers/asset.controller.ts`
- [Asset service](https://github.com/coppsary/motify-backend/blob/main/src/services/asset.service.ts): `src/services/asset.service.ts`
- [Object storage](https://github.com/coppsary/motify-backend/blob/main/packages/object-storage/supabase-storage.ts): `packages/object-storage/supabase-storage.ts`
- [Audio catalog](https://github.com/coppsary/motify-backend/blob/main/src/services/audio.service.ts): `src/services/audio.service.ts`

### Billing and Persistence

- [Payment service](https://github.com/coppsary/motify-backend/blob/main/src/services/payment.service.ts): `src/services/payment.service.ts`
- [Bakong API client](https://github.com/coppsary/motify-backend/blob/main/packages/bakong/client.ts): `packages/bakong/client.ts`
- [PostgreSQL schema](https://github.com/coppsary/motify-backend/blob/main/packages/database/schema.ts): `packages/database/schema.ts`

### Other components

- **Motify editor**

## Connections

- Motify editor → API server: calls API (evidence: `README.md`)
- API server → Auth routes: mounts routes (evidence: `src/server.ts`)
- Auth routes → Auth controller: dispatches (evidence: `src/routes/auth.routes.ts`)
- API server → Session middleware: resolves sessions (evidence: `src/server.ts`)
- Auth controller → Auth service: invokes (evidence: `src/controllers/auth.controller.ts`)
- Auth persistence → PostgreSQL schema: reads and writes (evidence: `src/repositories/auth.repository.ts`)
- Auth persistence → Supabase Auth: uses provider types (evidence: `src/repositories/auth.repository.ts`)
- API server → Project controller: configures (evidence: `src/server.ts`)
- Project controller → Project service: invokes (evidence: `src/controllers/project.controller.ts`)
- API server → AI generation agent: configures agent (evidence: `src/server.ts`)
- Generation records → AI generation agent: uses generation schemas (evidence: `src/repositories/motion-graph.repository.ts`)
- API server → Asset controller: mounts asset routes (evidence: `src/server.ts`)
- Asset controller → Asset service: invokes (evidence: `src/controllers/asset.controller.ts`)
- Asset service → Object storage: uses storage adapter (evidence: `src/services/asset.service.ts`)
- Audio catalog → PostgreSQL schema: persists catalog
- API server → Payment service: configures service (evidence: `src/server.ts`)
- Payment service → Bakong API client: checks payments (evidence: `src/services/payment.service.ts`)
- Payment service → Workspace service: uses workspace service (evidence: `src/services/payment.service.ts`)
- API server → PostgreSQL schema: creates database (evidence: `src/server.ts`)
