# apparyllisorg/simplypluralapi architecture

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

- Interactive diagram: https://gitdiagram.com/apparyllisorg/simplypluralapi
- Repository: https://github.com/apparyllisorg/simplypluralapi

## Overview

Simply Plural API is the backend for the Simply Plural app. The main workflow is an authenticated client request entering the Express server, being routed through versioned API endpoints to account, social, and user-data operations, then returning a response; avatar requests additionally validate and store files. Separate capabilities cover reports/exports, scheduled reminders and front notifications, chat/messages, billing, and PluralKit synchronization. The tree and excerpts support routing, storage, event-queue, and integration links; most individual handlers were not sampled, so their internal data access is not inferred.

Main entry points: [`src/api/v1/routes.ts`](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/routes.ts) (V1 routes), [`src/modules/server.ts`](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/server.ts) (Express server), [`src/api/v2/routes.ts`](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v2/routes.ts) (V2 routes), [`src/modules/events/eventController.ts`](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/events/eventController.ts) (Event controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_server["Express server<br/>[server.ts]"]
  node_v1routes["V1 routes<br/>[routes.ts]"]
  node_v2routes["V2 routes<br/>[routes.ts]"]
  node_mongo[("MongoDB<br/>[index.ts]")]
end

subgraph group_identity["Accounts and access"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_user["User accounts<br/>[user.ts]"]
end

subgraph group_product["Plural data"]
  node_friends["Friend operations<br/>[friendActions.ts]"]
  node_members["Members and groups<br/>[member.ts]"]
  node_front["Front and history<br/>[customFront.ts]"]
  node_notes["Notes and comments<br/>[note.ts]"]
  node_polls["Polls and filters<br/>[poll.ts]"]
  node_reports["Reports and export<br/>[generateReport.ts]"]
end

subgraph group_events["Events and messaging"]
  node_events["Event controller<br/>[eventController.ts]"]
  node_eventhandlers["Reminder and front handlers<br/>[frontChange.ts]"]
  node_messages["Messages and chat<br/>[messages.ts]"]
  node_mail["Mail transport<br/>[mail.ts]"]
end

subgraph group_integrations["Integrations and files"]
  node_avatar["Avatar endpoints<br/>[storage.ts]"]
  node_contentavatar["Content avatars<br/>[storage.content.ts]"]
  node_storage["Storage controller"]
  node_s3[("S3 object store<br/>[storageTargetS3.ts]")]
  node_pkapi["PluralKit API"]
  node_pk["PluralKit sync<br/>[sync.ts]"]
  node_pkdispatch["PluralKit dispatcher<br/>[controller.ts]"]
  node_stripe["Stripe billing"]
end

node_client(("App client"))

node_client -->|"sends requests"| node_server
node_server -->|"registers routes"| node_v1routes
node_server -->|"registers routes"| node_v2routes
node_server -->|"initializes"| node_mongo
node_v1routes -->|"dispatches"| node_auth
node_v1routes -->|"dispatches"| node_user
node_v1routes -->|"dispatches"| node_friends
node_v1routes -->|"dispatches"| node_members
node_v1routes -->|"dispatches"| node_front
node_v1routes -->|"dispatches"| node_notes
node_v1routes -->|"dispatches"| node_polls
node_v1routes -->|"dispatches"| node_reports
node_v1routes -->|"dispatches"| node_avatar
node_v1routes -->|"dispatches"| node_messages
node_v2routes -->|"dispatches"| node_friends
node_v2routes -->|"dispatches"| node_contentavatar
node_avatar -->|"stores files"| node_storage
node_contentavatar -->|"stores files"| node_storage
node_storage -->|"writes and reads"| node_s3
node_server -->|"starts controller"| node_events
node_events -->|"reads and queues"| node_mongo
node_events -->|"dispatches due events"| node_eventhandlers
node_server -->|"starts dispatcher"| node_pkdispatch
node_pk -->|"queues requests"| node_pkdispatch
node_pkdispatch -.->|"sends requests"| node_pkapi
node_server -->|"starts transport"| node_mail
node_server -->|"initializes billing"| node_stripe

click node_server "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/server.ts"
click node_v1routes "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/routes.ts"
click node_v2routes "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v2/routes.ts"
click node_auth "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/auth.ts"
click node_user "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/user.ts"
click node_friends "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/friendActions.ts"
click node_members "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/member.ts"
click node_front "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/customFront.ts"
click node_notes "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/note.ts"
click node_polls "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/poll.ts"
click node_reports "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/user/generateReport.ts"
click node_mongo "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/mongo/index.ts"
click node_avatar "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/storage.ts"
click node_contentavatar "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v2/storage/storage.content.ts"
click node_storage "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/storage/storageController.ts"
click node_s3 "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/storage/storageTargetS3.ts"
click node_events "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/events/eventController.ts"
click node_eventhandlers "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/events/frontChange.ts"
click node_messages "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/messages.ts"
click node_pk "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/integrations/pk/sync.ts"
click node_pkdispatch "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/integrations/pk/controller.ts"
click node_mail "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/mail.ts"
click node_stripe "https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/subscriptions/subscriptions.core.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_v1routes,node_v2routes,node_mongo,node_client toneBlue
class node_auth,node_user toneAmber
class node_friends,node_members,node_front,node_notes,node_polls,node_reports toneMint
class node_events,node_eventhandlers,node_messages,node_mail toneRose
class node_avatar,node_contentavatar,node_storage,node_s3,node_pkapi,node_pk,node_pkdispatch,node_stripe toneIndigo
```

## Components

### API runtime

- [Express server](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/server.ts): `src/modules/server.ts`
- [V1 routes](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/routes.ts): `src/api/v1/routes.ts`
- [V2 routes](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v2/routes.ts): `src/api/v2/routes.ts`
- [MongoDB](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/mongo/index.ts): `src/modules/mongo/index.ts`

### Accounts and access

- [Authentication](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/auth.ts): `src/api/v1/auth.ts`
- [User accounts](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/user.ts): `src/api/v1/user.ts`

### Plural data

- [Friend operations](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/friendActions.ts): `src/api/v1/friendActions.ts`
- [Members and groups](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/member.ts): `src/api/v1/member.ts`
- [Front and history](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/customFront.ts): `src/api/v1/customFront.ts`
- [Notes and comments](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/note.ts): `src/api/v1/note.ts`
- [Polls and filters](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/poll.ts): `src/api/v1/poll.ts`
- [Reports and export](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/user/generateReport.ts): `src/api/v1/user/generateReport.ts`

### Events and messaging

- [Event controller](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/events/eventController.ts): `src/modules/events/eventController.ts`
- [Reminder and front handlers](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/events/frontChange.ts): `src/modules/events/frontChange.ts`
- [Messages and chat](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/messages.ts): `src/api/v1/messages.ts`
- [Mail transport](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/mail.ts): `src/modules/mail.ts`

### Integrations and files

- [Avatar endpoints](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/storage.ts): `src/api/v1/storage.ts`
- [Content avatars](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v2/storage/storage.content.ts): `src/api/v2/storage/storage.content.ts`
- [Storage controller](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/storage/storageController.ts): `src/modules/storage/storageController.ts`
- [S3 object store](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/storage/storageTargetS3.ts): `src/modules/storage/storageTargetS3.ts`
- **PluralKit API**
- [PluralKit sync](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/integrations/pk/sync.ts): `src/modules/integrations/pk/sync.ts`
- [PluralKit dispatcher](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/modules/integrations/pk/controller.ts): `src/modules/integrations/pk/controller.ts`
- [Stripe billing](https://github.com/apparyllisorg/simplypluralapi/blob/release/src/api/v1/subscriptions/subscriptions.core.ts): `src/api/v1/subscriptions/subscriptions.core.ts`

### Other components

- **App client**

## Connections

- App client → Express server: sends requests
- Express server → V1 routes: registers routes
- Express server → V2 routes: registers routes
- Express server → MongoDB: initializes
- V1 routes → Authentication: dispatches
- V1 routes → User accounts: dispatches
- V1 routes → Friend operations: dispatches
- V1 routes → Members and groups: dispatches
- V1 routes → Front and history: dispatches
- V1 routes → Notes and comments: dispatches
- V1 routes → Polls and filters: dispatches
- V1 routes → Reports and export: dispatches
- V1 routes → Avatar endpoints: dispatches
- V1 routes → Messages and chat: dispatches
- V2 routes → Friend operations: dispatches
- V2 routes → Content avatars: dispatches
- Avatar endpoints → Storage controller: stores files
- Content avatars → Storage controller: stores files
- Storage controller → S3 object store: writes and reads
- Express server → Event controller: starts controller
- Event controller → MongoDB: reads and queues
- Event controller → Reminder and front handlers: dispatches due events
- Express server → PluralKit dispatcher: starts dispatcher
- PluralKit sync → PluralKit dispatcher: queues requests
- PluralKit dispatcher → PluralKit API: sends requests
- Express server → Mail transport: starts transport
- Express server → Stripe billing: initializes billing