# daviddems/fanwire architecture

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

- Interactive diagram: https://gitdiagram.com/daviddems/fanwire
- Repository: https://github.com/daviddems/fanwire

## Overview

Fanwire is a sports-discussion application: users browse game-aware feeds and search, publish posts with media, and manage profiles and notifications. The main runtime is a FastAPI backend with a React frontend; the README describes the frontend as scaffolded and AWS infrastructure as not deployed. The graph preserves the documented media-processing and sports-data capabilities, but some internal wiring is unsampled, so only documented or visible relationships are shown.

Main entry points: [`backend/app/main.py`](https://github.com/daviddems/fanwire/blob/main/backend/app/main.py) (FastAPI entrypoint), [`backend/app/users/routes.py`](https://github.com/daviddems/fanwire/blob/main/backend/app/users/routes.py) (User routes), [`backend/app/feed/routes.py`](https://github.com/daviddems/fanwire/blob/main/backend/app/feed/routes.py) (Feed and threads), [`backend/app/search/routes.py`](https://github.com/daviddems/fanwire/blob/main/backend/app/search/routes.py) (Search routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React application<br/>[App.tsx]"]
  node_routes_ui["Page routes<br/>[routes.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_identity["Accounts"]
  node_user_routes["User routes<br/>[routes.py]"]
  node_user_service["User services<br/>[service.py]"]
  node_auth["Token verification<br/>[auth.py]"]
end

subgraph group_content["Posts and media"]
  node_posts_routes["Post routes<br/>[routes.py]"]
  node_post_facade["Publish facade<br/>[facade.py]"]
  node_post_service["Post services<br/>[service.py]"]
  node_moderation["Post moderation<br/>[moderation.py]"]
  node_media_routes["Upload routes<br/>[routes.py]"]
  node_media_pipeline["Image processing<br/>[pipeline.py]"]
  node_media_state["Media state<br/>[state.py]"]
end

subgraph group_discovery["Feed and discovery"]
  node_feed_routes["Feed and threads<br/>[routes.py]"]
  node_feed_strategy["Feed strategies<br/>[strategies.py]"]
  node_search_routes["Search routes<br/>[routes.py]"]
end

subgraph group_platform["Events and notifications"]
  node_api["FastAPI entrypoint<br/>[main.py]"]
  node_events_routes["Sports data routes<br/>[routes.py]"]
  node_event_service["Event ingestion<br/>[ingestion.py]"]
  node_score_proxy["Live score proxy<br/>[proxy.py]"]
  node_event_bus["Post event bus<br/>[eventbus.py]"]
  node_notifications["Notifications<br/>[consumer.py]"]
end

node_person(("App user"))
node_cognito["Cognito identity"]
node_object_store[("S3 media buckets<br/>[storage-stack.ts]")]
node_sports_api["Sports data API"]
node_database[("Application database<br/>[db.py]")]

node_person -->|"uses"| node_web
node_web -->|"mounts routes"| node_routes_ui
node_web -->|"shares client"| node_api_client
node_api_client -->|"HTTP requests"| node_api
node_api -->|"mounts router"| node_user_routes
node_api -->|"mounts router"| node_posts_routes
node_api -->|"mounts router"| node_media_routes
node_api -->|"mounts router"| node_feed_routes
node_api -->|"mounts router"| node_search_routes
node_api -->|"mounts router"| node_events_routes
node_user_routes -->|"calls"| node_user_service
node_user_routes -->|"requires identity"| node_auth
node_auth -->|"verifies token"| node_cognito
node_user_routes -->|"reads and writes"| node_database
node_posts_routes -->|"publishes via"| node_post_facade
node_post_facade -->|"moderates"| node_moderation
node_post_facade -->|"creates post"| node_post_service
node_posts_routes -->|"calls actions"| node_post_service
node_media_routes -->|"records upload"| node_database
node_media_routes -->|"issues upload access"| node_object_store
node_object_store -->|"triggers processing"| node_media_pipeline
node_media_pipeline -->|"reads and publishes"| node_object_store
node_media_pipeline -->|"transitions status"| node_media_state
node_feed_routes -->|"selects posts"| node_feed_strategy
node_feed_routes -->|"loads replies"| node_post_service
node_feed_routes -->|"adds live scores"| node_score_proxy
node_search_routes -->|"searches accounts"| node_user_service
node_search_routes -->|"searches posts"| node_post_service
node_search_routes -->|"filters games"| node_events_routes
node_events_routes -->|"reads games"| node_database
node_event_service -->|"imports sports data"| node_sports_api
node_user_routes -->|"publishes follow events"| node_event_bus
node_event_bus -->|"dispatches events"| node_notifications
node_notifications -->|"stores notifications"| node_database

click node_web "https://github.com/daviddems/fanwire/blob/main/frontend/src/App.tsx"
click node_routes_ui "https://github.com/daviddems/fanwire/blob/main/frontend/src/routes/routes.tsx"
click node_api_client "https://github.com/daviddems/fanwire/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/daviddems/fanwire/blob/main/backend/app/main.py"
click node_user_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/users/routes.py"
click node_user_service "https://github.com/daviddems/fanwire/blob/main/backend/app/users/service.py"
click node_auth "https://github.com/daviddems/fanwire/blob/main/backend/app/users/auth.py"
click node_posts_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/posts/routes.py"
click node_post_facade "https://github.com/daviddems/fanwire/blob/main/backend/app/posts/facade.py"
click node_post_service "https://github.com/daviddems/fanwire/blob/main/backend/app/posts/service.py"
click node_moderation "https://github.com/daviddems/fanwire/blob/main/backend/app/posts/moderation.py"
click node_media_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/media/routes.py"
click node_media_pipeline "https://github.com/daviddems/fanwire/blob/main/backend/app/media/pipeline.py"
click node_media_state "https://github.com/daviddems/fanwire/blob/main/backend/app/media/state.py"
click node_object_store "https://github.com/daviddems/fanwire/blob/main/infra/lib/storage-stack.ts"
click node_feed_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/feed/routes.py"
click node_feed_strategy "https://github.com/daviddems/fanwire/blob/main/backend/app/feed/strategies.py"
click node_search_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/search/routes.py"
click node_events_routes "https://github.com/daviddems/fanwire/blob/main/backend/app/events/routes.py"
click node_event_service "https://github.com/daviddems/fanwire/blob/main/backend/app/events/ingestion.py"
click node_score_proxy "https://github.com/daviddems/fanwire/blob/main/backend/app/events/proxy.py"
click node_event_bus "https://github.com/daviddems/fanwire/blob/main/backend/app/eventbus.py"
click node_notifications "https://github.com/daviddems/fanwire/blob/main/backend/app/notifications/consumer.py"
click node_database "https://github.com/daviddems/fanwire/blob/main/backend/app/db.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_web,node_routes_ui,node_api_client,node_person toneBlue
class node_user_routes,node_user_service,node_auth,node_object_store,node_database toneAmber
class node_posts_routes,node_post_facade,node_post_service,node_moderation,node_media_routes,node_media_pipeline,node_media_state,node_sports_api toneMint
class node_feed_routes,node_feed_strategy,node_search_routes toneRose
class node_api,node_events_routes,node_event_service,node_score_proxy,node_event_bus,node_notifications,node_cognito toneIndigo
```

## Components

### Web client

- [React application](https://github.com/daviddems/fanwire/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Page routes](https://github.com/daviddems/fanwire/blob/main/frontend/src/routes/routes.tsx): `frontend/src/routes/routes.tsx`
- [API client](https://github.com/daviddems/fanwire/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Accounts

- [User routes](https://github.com/daviddems/fanwire/blob/main/backend/app/users/routes.py): `backend/app/users/routes.py`
- [User services](https://github.com/daviddems/fanwire/blob/main/backend/app/users/service.py): `backend/app/users/service.py`
- [Token verification](https://github.com/daviddems/fanwire/blob/main/backend/app/users/auth.py): `backend/app/users/auth.py`

### Posts and media

- [Post routes](https://github.com/daviddems/fanwire/blob/main/backend/app/posts/routes.py): `backend/app/posts/routes.py`
- [Publish facade](https://github.com/daviddems/fanwire/blob/main/backend/app/posts/facade.py): `backend/app/posts/facade.py`
- [Post services](https://github.com/daviddems/fanwire/blob/main/backend/app/posts/service.py): `backend/app/posts/service.py`
- [Post moderation](https://github.com/daviddems/fanwire/blob/main/backend/app/posts/moderation.py): `backend/app/posts/moderation.py`
- [Upload routes](https://github.com/daviddems/fanwire/blob/main/backend/app/media/routes.py): `backend/app/media/routes.py`
- [Image processing](https://github.com/daviddems/fanwire/blob/main/backend/app/media/pipeline.py): `backend/app/media/pipeline.py`
- [Media state](https://github.com/daviddems/fanwire/blob/main/backend/app/media/state.py): `backend/app/media/state.py`

### Feed and discovery

- [Feed and threads](https://github.com/daviddems/fanwire/blob/main/backend/app/feed/routes.py): `backend/app/feed/routes.py`
- [Feed strategies](https://github.com/daviddems/fanwire/blob/main/backend/app/feed/strategies.py): `backend/app/feed/strategies.py`
- [Search routes](https://github.com/daviddems/fanwire/blob/main/backend/app/search/routes.py): `backend/app/search/routes.py`

### Events and notifications

- [FastAPI entrypoint](https://github.com/daviddems/fanwire/blob/main/backend/app/main.py): `backend/app/main.py`
- [Sports data routes](https://github.com/daviddems/fanwire/blob/main/backend/app/events/routes.py): `backend/app/events/routes.py`
- [Event ingestion](https://github.com/daviddems/fanwire/blob/main/backend/app/events/ingestion.py): `backend/app/events/ingestion.py`
- [Live score proxy](https://github.com/daviddems/fanwire/blob/main/backend/app/events/proxy.py): `backend/app/events/proxy.py`
- [Post event bus](https://github.com/daviddems/fanwire/blob/main/backend/app/eventbus.py): `backend/app/eventbus.py`
- [Notifications](https://github.com/daviddems/fanwire/blob/main/backend/app/notifications/consumer.py): `backend/app/notifications/consumer.py`

### Other components

- **App user**
- **Cognito identity**
- [S3 media buckets](https://github.com/daviddems/fanwire/blob/main/infra/lib/storage-stack.ts): `infra/lib/storage-stack.ts`
- **Sports data API**
- [Application database](https://github.com/daviddems/fanwire/blob/main/backend/app/db.py): `backend/app/db.py`

## Connections

- App user → React application: uses
- React application → Page routes: mounts routes
- React application → API client: shares client
- API client → FastAPI entrypoint: HTTP requests
- FastAPI entrypoint → User routes: mounts router
- FastAPI entrypoint → Post routes: mounts router
- FastAPI entrypoint → Upload routes: mounts router
- FastAPI entrypoint → Feed and threads: mounts router
- FastAPI entrypoint → Search routes: mounts router
- FastAPI entrypoint → Sports data routes: mounts router
- User routes → User services: calls
- User routes → Token verification: requires identity
- Token verification → Cognito identity: verifies token
- User routes → Application database: reads and writes
- Post routes → Publish facade: publishes via
- Publish facade → Post moderation: moderates
- Publish facade → Post services: creates post
- Post routes → Post services: calls actions
- Upload routes → Application database: records upload
- Upload routes → S3 media buckets: issues upload access
- S3 media buckets → Image processing: triggers processing
- Image processing → S3 media buckets: reads and publishes
- Image processing → Media state: transitions status
- Feed and threads → Feed strategies: selects posts
- Feed and threads → Post services: loads replies
- Feed and threads → Live score proxy: adds live scores
- Search routes → User services: searches accounts
- Search routes → Post services: searches posts
- Search routes → Sports data routes: filters games
- Sports data routes → Application database: reads games
- Event ingestion → Sports data API: imports sports data
- User routes → Post event bus: publishes follow events
- Post event bus → Notifications: dispatches events
- Notifications → Application database: stores notifications