# mikekuriger/dreamr-backend architecture

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

- Interactive diagram: https://gitdiagram.com/mikekuriger/dreamr-backend
- Repository: https://github.com/mikekuriger/dreamr-backend

## Overview

Dreamr is a Flask backend for a mobile dream-journaling and analysis app. The mobile client calls the API for authentication and profile access, dream journaling, AI interpretation and imagery, chat, insights, and subscription management. In the main application, request handlers coordinate domain services, moderation, quota checks, and persistence; Apple notifications also verify signed events before updating subscription state. The README documents additional billing, reporting, admin, and Google Play flows whose internal routes were not sampled, so those are represented at the API boundary without guessed call paths.

Main entry points: [`app.py`](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py) (Flask REST API), [`apple_notifications.py`](https://github.com/mikekuriger/dreamr-backend/blob/main/apple_notifications.py) (Apple notifications), [`moderation.py`](https://github.com/mikekuriger/dreamr-backend/blob/main/moderation.py) (Content moderation), [`quota.py`](https://github.com/mikekuriger/dreamr-backend/blob/main/quota.py) (Credit accounting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounts"]
  node_api["Flask REST API<br/>[app.py]"]
  node_accounts["Accounts and profiles<br/>[app.py]"]
  node_reports_admin["Reports and admin<br/>[app.py]"]
end

subgraph group_dream["Dream experiences"]
  node_journal["Dream journal<br/>[app.py]"]
  node_interpret["Dream interpretation<br/>[app.py]"]
  node_prompts["Persona prompts<br/>[prompts.py]"]
  node_images["Dream imagery<br/>[app.py]"]
  node_chat["Follow-up chat<br/>[app.py]"]
  node_sessions["Chat sessions<br/>[sessions.py]"]
  node_insights["Dream insights<br/>[app.py]"]
end

subgraph group_billing["Plans and billing"]
  node_subscriptions["Subscription service<br/>[app.py]"]
  node_apple_events["Apple notifications"]
  node_billing_api["Billing and webhooks<br/>[app.py]"]
end

subgraph group_platform["Shared services"]
  node_moderation["Content moderation<br/>[moderation.py]"]
  node_quota["Credit accounting<br/>[quota.py]"]
  node_database[("Application database<br/>[app.py]")]
end

node_mobile(("Mobile app"))
node_apple_store["Apple App Store"]
node_google_play["Google Play"]
node_openai["OpenAI API"]

node_mobile -->|"calls API"| node_api
node_api -->|"routes account requests"| node_accounts
node_api -->|"routes dream requests"| node_journal
node_api -->|"handles AI requests"| node_interpret
node_interpret -->|"uses personas"| node_prompts
node_interpret -->|"screens content"| node_moderation
node_images -->|"checks and decrements"| node_quota
node_api -->|"routes image requests"| node_images
node_api -->|"routes chat requests"| node_chat
node_chat -->|"stores history"| node_sessions
node_api -->|"routes insight requests"| node_insights
node_api -->|"routes billing requests"| node_billing_api
node_billing_api -->|"handles purchases"| node_subscriptions
node_apple_store -->|"sends notifications"| node_apple_events
node_apple_events -->|"updates subscription records"| node_database
node_billing_api -->|"verifies transactions"| node_apple_events
node_billing_api -.->|"verifies purchases"| node_google_play
node_billing_api -->|"screens generated content"| node_moderation
node_moderation -->|"checks content"| node_openai
node_interpret -.->|"requests interpretations"| node_openai
node_images -.->|"generates imagery"| node_openai
node_api -->|"checks image credits"| node_quota
node_accounts -.->|"reads and writes"| node_database
node_journal -.->|"reads and writes"| node_database
node_insights -.->|"reads and writes"| node_database
node_subscriptions -.->|"reads and writes"| node_database
node_quota -.->|"accounts credits"| node_database
node_api -->|"routes reports and ops"| node_reports_admin

click node_api "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_accounts "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_journal "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_interpret "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_prompts "https://github.com/mikekuriger/dreamr-backend/blob/main/prompts.py"
click node_images "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_chat "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_sessions "https://github.com/mikekuriger/dreamr-backend/blob/main/sessions.py"
click node_insights "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_subscriptions "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_apple_events "https://github.com/mikekuriger/dreamr-backend/blob/main/apple_notifications.py"
click node_billing_api "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_moderation "https://github.com/mikekuriger/dreamr-backend/blob/main/moderation.py"
click node_quota "https://github.com/mikekuriger/dreamr-backend/blob/main/quota.py"
click node_database "https://github.com/mikekuriger/dreamr-backend/blob/main/app.py"
click node_reports_admin "https://github.com/mikekuriger/dreamr-backend/blob/main/app.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_api,node_accounts,node_reports_admin toneBlue
class node_journal,node_interpret,node_prompts,node_images,node_chat,node_sessions,node_insights toneAmber
class node_subscriptions,node_apple_events,node_billing_api,node_openai toneMint
class node_moderation,node_quota,node_database toneRose
class node_mobile,node_apple_store,node_google_play toneIndigo
```

## Components

### API and accounts

- [Flask REST API](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Accounts and profiles](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Reports and admin](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`

### Dream experiences

- [Dream journal](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Dream interpretation](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Persona prompts](https://github.com/mikekuriger/dreamr-backend/blob/main/prompts.py): `prompts.py`
- [Dream imagery](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Follow-up chat](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Chat sessions](https://github.com/mikekuriger/dreamr-backend/blob/main/sessions.py): `sessions.py`
- [Dream insights](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`

### Plans and billing

- [Subscription service](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`
- [Apple notifications](https://github.com/mikekuriger/dreamr-backend/blob/main/apple_notifications.py): `apple_notifications.py`
- [Billing and webhooks](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`

### Shared services

- [Content moderation](https://github.com/mikekuriger/dreamr-backend/blob/main/moderation.py): `moderation.py`
- [Credit accounting](https://github.com/mikekuriger/dreamr-backend/blob/main/quota.py): `quota.py`
- [Application database](https://github.com/mikekuriger/dreamr-backend/blob/main/app.py): `app.py`

### Other components

- **Mobile app**
- **Apple App Store**
- **Google Play**
- **OpenAI API**

## Connections

- Mobile app → Flask REST API: calls API (evidence: `README.md`)
- Flask REST API → Accounts and profiles: routes account requests (evidence: `README.md`)
- Flask REST API → Dream journal: routes dream requests (evidence: `README.md`)
- Flask REST API → Dream interpretation: handles AI requests (evidence: `README.md`)
- Dream interpretation → Persona prompts: uses personas (evidence: `app.py`)
- Dream interpretation → Content moderation: screens content (evidence: `app.py`)
- Dream imagery → Credit accounting: checks and decrements (evidence: `app.py`)
- Flask REST API → Dream imagery: routes image requests (evidence: `app.py`)
- Flask REST API → Follow-up chat: routes chat requests (evidence: `README.md`)
- Follow-up chat → Chat sessions: stores history (evidence: `README.md`)
- Flask REST API → Dream insights: routes insight requests (evidence: `README.md`)
- Flask REST API → Billing and webhooks: routes billing requests (evidence: `README.md`)
- Billing and webhooks → Subscription service: handles purchases (evidence: `README.md`)
- Apple App Store → Apple notifications: sends notifications (evidence: `apple_notifications.py`)
- Apple notifications → Application database: updates subscription records (evidence: `apple_notifications.py`)
- Billing and webhooks → Apple notifications: verifies transactions (evidence: `apple_notifications.py`)
- Billing and webhooks → Google Play: verifies purchases (evidence: `README.md`)
- Billing and webhooks → Content moderation: screens generated content (evidence: `app.py`)
- Content moderation → OpenAI API: checks content (evidence: `moderation.py`)
- Dream interpretation → OpenAI API: requests interpretations (evidence: `README.md`)
- Dream imagery → OpenAI API: generates imagery (evidence: `README.md`)
- Flask REST API → Credit accounting: checks image credits (evidence: `app.py`)
- Accounts and profiles → Application database: reads and writes (evidence: `app.py`)
- Dream journal → Application database: reads and writes (evidence: `app.py`)
- Dream insights → Application database: reads and writes (evidence: `app.py`)
- Subscription service → Application database: reads and writes (evidence: `app.py`)
- Credit accounting → Application database: accounts credits (evidence: `quota.py`)
- Flask REST API → Reports and admin: routes reports and ops (evidence: `README.md`)