# vulcio/oneverse architecture

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

- Interactive diagram: https://gitdiagram.com/vulcio/oneverse
- Repository: https://github.com/vulcio/oneverse

## Overview

Oneverse is a shared account and collaboration platform whose apps serve worship teams, musicians, and planners. A principal workflow is a musician creating a structured song in Songverse, organizing songs into songbooks or sets, and sharing them with a team; Planiverse supports the parallel event-planning workflow, while screens and live sessions support use at a venue. The API, shared database, and storage underpin these products. The README documents product capabilities and shared-API relationships; sampled source confirms only selected API and storage calls, so other internal links are omitted.

Main entry points: [`apps/web/src/components/app-shell.tsx`](https://github.com/vulcio/oneverse/blob/main/apps/web/src/components/app-shell.tsx) (Songverse), [`apps/api/src/app.module.ts`](https://github.com/vulcio/oneverse/blob/main/apps/api/src/app.module.ts) (Oneverse API), [`apps/planiverse/src/routes/_protected/organizations/index.tsx`](https://github.com/vulcio/oneverse/blob/main/apps/planiverse/src/routes/_protected/organizations/index.tsx) (Planiverse), [`apps/api/src/setlists/setlists.service.ts`](https://github.com/vulcio/oneverse/blob/main/apps/api/src/setlists/setlists.service.ts) (Sets and sharing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Accounts and access"]
  node_oneverse["Oneverse account<br/>[index.tsx]"]
  node_auth["Authentication"]
end

subgraph group_songs["Songs and sets"]
  node_songverse["Songverse<br/>[app-shell.tsx]"]
  node_songcharts["Song charts<br/>[parser.ts]"]
  node_songversions["Song versions"]
  node_catalogue["Global catalogue"]
  node_songbooks["Songbooks"]
  node_sets["Sets and sharing"]
  node_arrangements["Arrangements"]
  node_attachment["Song attachments"]
end

subgraph group_planning["Planning and teams"]
  node_planiverse["Planiverse<br/>[index.tsx]"]
  node_events["Events and rotas"]
  node_organizations["Organizations"]
  node_teams["Teams and roles<br/>[teams.service.ts]"]
end

subgraph group_live["Live and screens"]
  node_screens["Screens<br/>[screens.service.ts]"]
  node_sync["Live sessions<br/>[sync.server.ts]"]
  node_operator["Operator console"]
end

subgraph group_platform["Shared platform"]
  node_api["Oneverse API<br/>[app.module.ts]"]
  node_database[("PostgreSQL database<br/>[seed.ts]")]
  node_storage["File storage<br/>[storage.service.ts]"]
  node_ownstorage["Organization storage"]
end

node_musician(("Musician"))
node_planner(("Planner"))

node_musician -->|"uses"| node_songverse
node_planner -->|"uses"| node_planiverse
node_songverse -->|"signs in with"| node_oneverse
node_planiverse -->|"shares accounts"| node_oneverse
node_oneverse -->|"authenticates through"| node_auth
node_songverse -->|"uses shared API"| node_api
node_planiverse -->|"uses shared API"| node_api
node_songverse -->|"parses charts with"| node_songcharts
node_songverse -->|"manages songs through"| node_songversions
node_songversions -->|"submits songs to"| node_catalogue
node_songverse -->|"organizes songs in"| node_songbooks
node_songverse -->|"plans services with"| node_sets
node_sets -->|"uses arrangements"| node_arrangements
node_planiverse -->|"plans events through"| node_events
node_planiverse -->|"manages"| node_organizations
node_organizations -->|"organizes"| node_teams
node_api -->|"uses Prisma"| node_database
node_api -->|"stores files with"| node_storage
node_api -->|"supports organization buckets"| node_ownstorage
node_ownstorage -->|"moves files through"| node_storage
node_api -->|"handles attachments through"| node_attachment
node_sets -->|"displayed on"| node_screens
node_screens -->|"supports live sessions"| node_sync
node_sync -->|"drives"| node_operator

click node_oneverse "https://github.com/vulcio/oneverse/blob/main/apps/oneverse/src/routes/index.tsx"
click node_auth "https://github.com/vulcio/oneverse/tree/main/apps/api/src/auth"
click node_songverse "https://github.com/vulcio/oneverse/blob/main/apps/web/src/components/app-shell.tsx"
click node_songcharts "https://github.com/vulcio/oneverse/blob/main/packages/core/src/chordpro/parser.ts"
click node_songversions "https://github.com/vulcio/oneverse/blob/main/apps/api/src/song-versions/song-versions.service.ts"
click node_catalogue "https://github.com/vulcio/oneverse/blob/main/apps/api/src/publishing/publishing.service.ts"
click node_songbooks "https://github.com/vulcio/oneverse/blob/main/apps/api/src/songbooks/songbooks.service.ts"
click node_sets "https://github.com/vulcio/oneverse/blob/main/apps/api/src/setlists/setlists.service.ts"
click node_arrangements "https://github.com/vulcio/oneverse/blob/main/apps/api/src/arrangements/arrangements.service.ts"
click node_planiverse "https://github.com/vulcio/oneverse/blob/main/apps/planiverse/src/routes/_protected/organizations/index.tsx"
click node_events "https://github.com/vulcio/oneverse/blob/main/apps/api/src/team-events/team-events.service.ts"
click node_organizations "https://github.com/vulcio/oneverse/blob/main/apps/api/src/organizations/organizations.service.ts"
click node_teams "https://github.com/vulcio/oneverse/blob/main/apps/api/src/teams/teams.service.ts"
click node_screens "https://github.com/vulcio/oneverse/blob/main/apps/api/src/screens/screens.service.ts"
click node_sync "https://github.com/vulcio/oneverse/blob/main/apps/api/src/sync/sync.server.ts"
click node_operator "https://github.com/vulcio/oneverse/blob/main/packages/operator/src/components/operator-console.tsx"
click node_api "https://github.com/vulcio/oneverse/blob/main/apps/api/src/app.module.ts"
click node_database "https://github.com/vulcio/oneverse/blob/main/packages/db/src/seed.ts"
click node_storage "https://github.com/vulcio/oneverse/blob/main/apps/api/src/storage/storage.service.ts"
click node_ownstorage "https://github.com/vulcio/oneverse/blob/main/apps/api/src/own-storage/own-storage.service.ts"
click node_attachment "https://github.com/vulcio/oneverse/blob/main/apps/api/src/attachments/attachments.service.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_oneverse,node_auth toneBlue
class node_songverse,node_songcharts,node_songversions,node_catalogue,node_songbooks,node_sets,node_arrangements,node_attachment toneAmber
class node_planiverse,node_events,node_organizations,node_teams toneMint
class node_screens,node_sync,node_operator toneRose
class node_api,node_database,node_storage,node_ownstorage,node_musician,node_planner toneIndigo
```

## Components

### Accounts and access

- [Oneverse account](https://github.com/vulcio/oneverse/blob/main/apps/oneverse/src/routes/index.tsx): `apps/oneverse/src/routes/index.tsx`
- [Authentication](https://github.com/vulcio/oneverse/tree/main/apps/api/src/auth): `apps/api/src/auth`

### Songs and sets

- [Songverse](https://github.com/vulcio/oneverse/blob/main/apps/web/src/components/app-shell.tsx): `apps/web/src/components/app-shell.tsx`
- [Song charts](https://github.com/vulcio/oneverse/blob/main/packages/core/src/chordpro/parser.ts): `packages/core/src/chordpro/parser.ts`
- [Song versions](https://github.com/vulcio/oneverse/blob/main/apps/api/src/song-versions/song-versions.service.ts): `apps/api/src/song-versions/song-versions.service.ts`
- [Global catalogue](https://github.com/vulcio/oneverse/blob/main/apps/api/src/publishing/publishing.service.ts): `apps/api/src/publishing/publishing.service.ts`
- [Songbooks](https://github.com/vulcio/oneverse/blob/main/apps/api/src/songbooks/songbooks.service.ts): `apps/api/src/songbooks/songbooks.service.ts`
- [Sets and sharing](https://github.com/vulcio/oneverse/blob/main/apps/api/src/setlists/setlists.service.ts): `apps/api/src/setlists/setlists.service.ts`
- [Arrangements](https://github.com/vulcio/oneverse/blob/main/apps/api/src/arrangements/arrangements.service.ts): `apps/api/src/arrangements/arrangements.service.ts`
- [Song attachments](https://github.com/vulcio/oneverse/blob/main/apps/api/src/attachments/attachments.service.ts): `apps/api/src/attachments/attachments.service.ts`

### Planning and teams

- [Planiverse](https://github.com/vulcio/oneverse/blob/main/apps/planiverse/src/routes/_protected/organizations/index.tsx): `apps/planiverse/src/routes/_protected/organizations/index.tsx`
- [Events and rotas](https://github.com/vulcio/oneverse/blob/main/apps/api/src/team-events/team-events.service.ts): `apps/api/src/team-events/team-events.service.ts`
- [Organizations](https://github.com/vulcio/oneverse/blob/main/apps/api/src/organizations/organizations.service.ts): `apps/api/src/organizations/organizations.service.ts`
- [Teams and roles](https://github.com/vulcio/oneverse/blob/main/apps/api/src/teams/teams.service.ts): `apps/api/src/teams/teams.service.ts`

### Live and screens

- [Screens](https://github.com/vulcio/oneverse/blob/main/apps/api/src/screens/screens.service.ts): `apps/api/src/screens/screens.service.ts`
- [Live sessions](https://github.com/vulcio/oneverse/blob/main/apps/api/src/sync/sync.server.ts): `apps/api/src/sync/sync.server.ts`
- [Operator console](https://github.com/vulcio/oneverse/blob/main/packages/operator/src/components/operator-console.tsx): `packages/operator/src/components/operator-console.tsx`

### Shared platform

- [Oneverse API](https://github.com/vulcio/oneverse/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [PostgreSQL database](https://github.com/vulcio/oneverse/blob/main/packages/db/src/seed.ts): `packages/db/src/seed.ts`
- [File storage](https://github.com/vulcio/oneverse/blob/main/apps/api/src/storage/storage.service.ts): `apps/api/src/storage/storage.service.ts`
- [Organization storage](https://github.com/vulcio/oneverse/blob/main/apps/api/src/own-storage/own-storage.service.ts): `apps/api/src/own-storage/own-storage.service.ts`

### Other components

- **Musician**
- **Planner**

## Connections

- Musician → Songverse: uses
- Planner → Planiverse: uses
- Songverse → Oneverse account: signs in with
- Planiverse → Oneverse account: shares accounts
- Oneverse account → Authentication: authenticates through
- Songverse → Oneverse API: uses shared API
- Planiverse → Oneverse API: uses shared API
- Songverse → Song charts: parses charts with
- Songverse → Song versions: manages songs through
- Song versions → Global catalogue: submits songs to
- Songverse → Songbooks: organizes songs in
- Songverse → Sets and sharing: plans services with
- Sets and sharing → Arrangements: uses arrangements
- Planiverse → Events and rotas: plans events through
- Planiverse → Organizations: manages
- Organizations → Teams and roles: organizes
- Oneverse API → PostgreSQL database: uses Prisma
- Oneverse API → File storage: stores files with
- Oneverse API → Organization storage: supports organization buckets
- Organization storage → File storage: moves files through (evidence: `apps/api/src/own-storage/own-storage.service.ts`)
- Oneverse API → Song attachments: handles attachments through
- Sets and sharing → Screens: displayed on
- Screens → Live sessions: supports live sessions
- Live sessions → Operator console: drives