# cfa-huddle/huddle-api architecture

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

- Interactive diagram: https://gitdiagram.com/cfa-huddle/huddle-api
- Repository: https://github.com/cfa-huddle/huddle-api

## Overview

Huddle is a backend API for restaurant-team accounts, location memberships and roles, posts, and push notifications. The main workflow is a mobile client calling the FastAPI routes: requests are authenticated into a user context, then domain services enforce permissions and persist or retrieve data; creating a post also finds location members and dispatches push notifications. User management additionally coordinates identity-provider accounts with location memberships. The README mentions training and feedback, but the supplied tree and sampled source do not expose their implementation, so those capabilities are not mapped. Some route and service wiring is inferred only from filenames and remains unexpanded.

Main entry points: [`app/main.py`](https://github.com/cfa-huddle/huddle-api/blob/main/app/main.py) (FastAPI entry), [`app/core/context.py`](https://github.com/cfa-huddle/huddle-api/blob/main/app/core/context.py) (Request context), [`app/service/post_service.py`](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/post_service.py) (Team posts), [`app/service/notification_service.py`](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/notification_service.py) (Push delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_main["FastAPI entry<br/>[main.py]"]
  node_users_api["User routes<br/>[users.py]"]
  node_membership_api["Membership routes<br/>[memberships.py]"]
  node_posts_api["Post routes<br/>[posts.py]"]
  node_notifications_api["Notification routes<br/>[notifications.py]"]
  node_context["Request context<br/>[context.py]"]
  node_auth["Token validation<br/>[auth.py]"]
end

subgraph group_domain["Team workflows"]
  node_user_service["User management<br/>[user_service.py]"]
  node_membership_service["Location memberships"]
  node_post_service["Team posts<br/>[post_service.py]"]
  node_notification_service["Push delivery"]
  node_push_tokens["Push token registry"]
end

subgraph group_storage["Data access"]
  node_db_helper["DynamoDB adapter<br/>[db.py]"]
  node_membership_model["Roles and memberships"]
  node_user_model["User records<br/>[user_model.py]"]
  node_post_model["Post records<br/>[post_model.py]"]
end

subgraph group_integrations["External services"]
  node_dynamo[("DynamoDB")]
  node_cognito["Cognito identity"]
  node_jwks["JWKS endpoint"]
  node_expo["Expo push service"]
end

node_client(("Mobile client"))

node_client -->|"calls API"| node_main
node_main -->|"dispatches"| node_users_api
node_main -->|"dispatches"| node_membership_api
node_main -->|"dispatches"| node_posts_api
node_main -->|"dispatches"| node_notifications_api
node_users_api -->|"resolves identity"| node_context
node_membership_api -->|"resolves identity"| node_context
node_posts_api -->|"resolves identity"| node_context
node_notifications_api -->|"resolves identity"| node_context
node_context -->|"validates token"| node_auth
node_auth -->|"fetches keys"| node_jwks
node_users_api -->|"invokes"| node_user_service
node_membership_api -->|"invokes"| node_membership_service
node_posts_api -->|"invokes"| node_post_service
node_notifications_api -->|"manages tokens"| node_push_tokens
node_user_service -->|"creates and lists users"| node_cognito
node_user_service -->|"assigns memberships"| node_membership_service
node_post_service -->|"finds recipients"| node_membership_service
node_post_service -->|"notifies members"| node_notification_service
node_membership_service -->|"reads and writes"| node_db_helper
node_post_service -->|"reads and writes"| node_db_helper
node_push_tokens -->|"reads and writes"| node_db_helper
node_db_helper -->|"accesses tables"| node_dynamo
node_notification_service -->|"loads tokens"| node_push_tokens
node_notification_service -->|"deactivates invalid tokens"| node_push_tokens
node_notification_service -->|"publishes pushes"| node_expo

click node_main "https://github.com/cfa-huddle/huddle-api/blob/main/app/main.py"
click node_users_api "https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/users.py"
click node_membership_api "https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/memberships.py"
click node_posts_api "https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/posts.py"
click node_notifications_api "https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/notifications.py"
click node_context "https://github.com/cfa-huddle/huddle-api/blob/main/app/core/context.py"
click node_auth "https://github.com/cfa-huddle/huddle-api/blob/main/app/core/auth.py"
click node_user_service "https://github.com/cfa-huddle/huddle-api/blob/main/app/service/user_service.py"
click node_membership_service "https://github.com/cfa-huddle/huddle-api/blob/main/app/service/membership_service.py"
click node_post_service "https://github.com/cfa-huddle/huddle-api/blob/main/app/service/post_service.py"
click node_notification_service "https://github.com/cfa-huddle/huddle-api/blob/main/app/service/notification_service.py"
click node_push_tokens "https://github.com/cfa-huddle/huddle-api/blob/main/app/service/push_token_repository.py"
click node_db_helper "https://github.com/cfa-huddle/huddle-api/blob/main/app/db.py"
click node_membership_model "https://github.com/cfa-huddle/huddle-api/blob/main/app/model/membership_model.py"
click node_user_model "https://github.com/cfa-huddle/huddle-api/blob/main/app/model/user_model.py"
click node_post_model "https://github.com/cfa-huddle/huddle-api/blob/main/app/model/post_model.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_main,node_users_api,node_membership_api,node_posts_api,node_notifications_api,node_context,node_auth,node_client toneBlue
class node_user_service,node_membership_service,node_post_service,node_notification_service,node_push_tokens toneAmber
class node_db_helper,node_membership_model,node_user_model,node_post_model toneMint
class node_dynamo,node_cognito,node_jwks,node_expo toneRose
```

## Components

### API and identity

- [FastAPI entry](https://github.com/cfa-huddle/huddle-api/blob/main/app/main.py): `app/main.py`
- [User routes](https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/users.py): `app/api/v1/users.py`
- [Membership routes](https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/memberships.py): `app/api/v1/memberships.py`
- [Post routes](https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/posts.py): `app/api/v1/posts.py`
- [Notification routes](https://github.com/cfa-huddle/huddle-api/blob/main/app/api/v1/notifications.py): `app/api/v1/notifications.py`
- [Request context](https://github.com/cfa-huddle/huddle-api/blob/main/app/core/context.py): `app/core/context.py`
- [Token validation](https://github.com/cfa-huddle/huddle-api/blob/main/app/core/auth.py): `app/core/auth.py`

### Team workflows

- [User management](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/user_service.py): `app/service/user_service.py`
- [Location memberships](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/membership_service.py): `app/service/membership_service.py`
- [Team posts](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/post_service.py): `app/service/post_service.py`
- [Push delivery](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/notification_service.py): `app/service/notification_service.py`
- [Push token registry](https://github.com/cfa-huddle/huddle-api/blob/main/app/service/push_token_repository.py): `app/service/push_token_repository.py`

### Data access

- [DynamoDB adapter](https://github.com/cfa-huddle/huddle-api/blob/main/app/db.py): `app/db.py`
- [Roles and memberships](https://github.com/cfa-huddle/huddle-api/blob/main/app/model/membership_model.py): `app/model/membership_model.py`
- [User records](https://github.com/cfa-huddle/huddle-api/blob/main/app/model/user_model.py): `app/model/user_model.py`
- [Post records](https://github.com/cfa-huddle/huddle-api/blob/main/app/model/post_model.py): `app/model/post_model.py`

### External services

- **DynamoDB**
- **Cognito identity**
- **JWKS endpoint**
- **Expo push service**

### Other components

- **Mobile client**

## Connections

- Mobile client → FastAPI entry: calls API
- FastAPI entry → User routes: dispatches
- FastAPI entry → Membership routes: dispatches
- FastAPI entry → Post routes: dispatches
- FastAPI entry → Notification routes: dispatches
- User routes → Request context: resolves identity
- Membership routes → Request context: resolves identity
- Post routes → Request context: resolves identity
- Notification routes → Request context: resolves identity
- Request context → Token validation: validates token
- Token validation → JWKS endpoint: fetches keys
- User routes → User management: invokes
- Membership routes → Location memberships: invokes
- Post routes → Team posts: invokes
- Notification routes → Push token registry: manages tokens
- User management → Cognito identity: creates and lists users
- User management → Location memberships: assigns memberships
- Team posts → Location memberships: finds recipients
- Team posts → Push delivery: notifies members
- Location memberships → DynamoDB adapter: reads and writes
- Team posts → DynamoDB adapter: reads and writes
- Push token registry → DynamoDB adapter: reads and writes
- DynamoDB adapter → DynamoDB: accesses tables
- Push delivery → Push token registry: loads tokens
- Push delivery → Push token registry: deactivates invalid tokens
- Push delivery → Expo push service: publishes pushes