# zzstar101/fish architecture

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

- Interactive diagram: https://gitdiagram.com/zzstar101/fish
- Repository: https://github.com/zzstar101/fish

## Overview

FISH (鱼小应) is a campus-only secondhand marketplace built around on-campus, in-person handoffs—not platform payment or shipping. A user signs in, finds or publishes a listing, and can chat with its owner; a buyer can also post a wish, which the background worker matches against listings and turns into an in-app notification. The parties can then propose and complete a meetup transaction. Groups reflect product stages and supporting runtime layers. The README documents several capabilities whose detailed source was not sampled; those are represented at domain level without implying unverified internal calls.

Main entry points: [`apps/api/src/app.ts`](https://github.com/zzstar101/fish/blob/main/apps/api/src/app.ts) (HTTP API), [`packages/db/src/schema`](https://github.com/zzstar101/fish/tree/main/packages/db/src/schema) (PostgreSQL), [`apps/api/src/modules/conversations`](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/conversations) (Chat and realtime), [`apps/api/src/modules/realtime`](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/realtime) (WebSocket hub)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User experiences"]
  node_mobile["Mobile web"]
  node_pc["PC web"]
  node_miniapp["Miniapp"]
end

subgraph group_market["Marketplace"]
  node_auth["Campus identity"]
  node_listings["Listings and search"]
  node_uploads["Media uploads"]
  node_moderation["Content moderation"]
end

subgraph group_engagement["Matching and communication"]
  node_wishes["Wish wall"]
  node_matching["Match jobs"]
  node_worker["Job worker<br/>[index.ts]"]
  node_notifications["In-app notifications"]
  node_chat["Chat and realtime"]
  node_realtime["WebSocket hub"]
end

subgraph group_trade["Meetup and governance"]
  node_transactions["Meetup transactions"]
  node_profile["Profiles"]
  node_governance["Admin governance"]
end

subgraph group_runtime["Platform runtime"]
  node_api["HTTP API<br/>[app.ts]"]
  node_contracts["Shared contracts"]
  node_db[("PostgreSQL")]
  node_objectstore[("S3 storage")]
end

node_people(("Campus users"))

node_people -->|"use"| node_mobile
node_people -->|"use"| node_pc
node_people -->|"use"| node_miniapp
node_mobile -->|"HTTP requests"| node_api
node_pc -->|"HTTP requests"| node_api
node_miniapp -->|"API requests"| node_api
node_mobile -->|"WebSocket"| node_realtime
node_pc -->|"WebSocket"| node_realtime
node_api -->|"validates against"| node_contracts
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_listings
node_api -->|"dispatches"| node_uploads
node_api -->|"dispatches"| node_moderation
node_api -->|"dispatches"| node_wishes
node_api -->|"dispatches"| node_notifications
node_api -->|"dispatches"| node_chat
node_api -->|"mounts"| node_realtime
node_api -->|"dispatches"| node_transactions
node_api -->|"dispatches"| node_profile
node_api -->|"mounts"| node_governance
node_api -->|"reads and writes"| node_db
node_worker -->|"runs jobs"| node_matching
node_matching -->|"reads and writes"| node_db
node_matching -->|"creates notifications"| node_notifications
node_uploads -.->|"presigns and verifies"| node_objectstore
node_listings -->|"reads and writes"| node_db
node_wishes -->|"reads and writes"| node_db
node_auth -->|"reads and writes"| node_db
node_chat -->|"reads and writes"| node_db
node_chat -->|"publishes events"| node_realtime
node_transactions -->|"reads and writes"| node_db
node_transactions -->|"writes system messages"| node_chat
node_notifications -->|"reads and writes"| node_db
node_profile -->|"reads"| node_db
node_governance -->|"reads and writes"| node_db

click node_mobile "https://github.com/zzstar101/fish/tree/main/apps/web/src"
click node_pc "https://github.com/zzstar101/fish/tree/main/apps/web-pc/src"
click node_miniapp "https://github.com/zzstar101/fish/tree/main/apps/miniapp/src"
click node_api "https://github.com/zzstar101/fish/blob/main/apps/api/src/app.ts"
click node_contracts "https://github.com/zzstar101/fish/tree/main/packages/contracts/src"
click node_db "https://github.com/zzstar101/fish/tree/main/packages/db/src/schema"
click node_auth "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/auth"
click node_listings "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/listings"
click node_uploads "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/uploads"
click node_moderation "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/moderation"
click node_wishes "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/wishes"
click node_matching "https://github.com/zzstar101/fish/tree/main/apps/worker/src/jobs/matching"
click node_worker "https://github.com/zzstar101/fish/blob/main/apps/worker/src/index.ts"
click node_notifications "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/notifications"
click node_chat "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/conversations"
click node_realtime "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/realtime"
click node_transactions "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/transactions"
click node_profile "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/profile"
click node_governance "https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/admin"

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_mobile,node_pc,node_miniapp,node_people toneBlue
class node_auth,node_listings,node_uploads,node_moderation toneAmber
class node_wishes,node_matching,node_worker,node_notifications,node_chat,node_realtime toneMint
class node_transactions,node_profile,node_governance toneRose
class node_api,node_contracts,node_db,node_objectstore toneIndigo
```

## Components

### User experiences

- [Mobile web](https://github.com/zzstar101/fish/tree/main/apps/web/src): `apps/web/src`
- [PC web](https://github.com/zzstar101/fish/tree/main/apps/web-pc/src): `apps/web-pc/src`
- [Miniapp](https://github.com/zzstar101/fish/tree/main/apps/miniapp/src): `apps/miniapp/src`

### Marketplace

- [Campus identity](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/auth): `apps/api/src/modules/auth`
- [Listings and search](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/listings): `apps/api/src/modules/listings`
- [Media uploads](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/uploads): `apps/api/src/modules/uploads`
- [Content moderation](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/moderation): `apps/api/src/modules/moderation`

### Matching and communication

- [Wish wall](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/wishes): `apps/api/src/modules/wishes`
- [Match jobs](https://github.com/zzstar101/fish/tree/main/apps/worker/src/jobs/matching): `apps/worker/src/jobs/matching`
- [Job worker](https://github.com/zzstar101/fish/blob/main/apps/worker/src/index.ts): `apps/worker/src/index.ts`
- [In-app notifications](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/notifications): `apps/api/src/modules/notifications`
- [Chat and realtime](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/conversations): `apps/api/src/modules/conversations`
- [WebSocket hub](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/realtime): `apps/api/src/modules/realtime`

### Meetup and governance

- [Meetup transactions](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/transactions): `apps/api/src/modules/transactions`
- [Profiles](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/profile): `apps/api/src/modules/profile`
- [Admin governance](https://github.com/zzstar101/fish/tree/main/apps/api/src/modules/admin): `apps/api/src/modules/admin`

### Platform runtime

- [HTTP API](https://github.com/zzstar101/fish/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Shared contracts](https://github.com/zzstar101/fish/tree/main/packages/contracts/src): `packages/contracts/src`
- [PostgreSQL](https://github.com/zzstar101/fish/tree/main/packages/db/src/schema): `packages/db/src/schema`
- **S3 storage**

### Other components

- **Campus users**

## Connections

- Campus users → Mobile web: use
- Campus users → PC web: use
- Campus users → Miniapp: use
- Mobile web → HTTP API: HTTP requests
- PC web → HTTP API: HTTP requests
- Miniapp → HTTP API: API requests
- Mobile web → WebSocket hub: WebSocket
- PC web → WebSocket hub: WebSocket
- HTTP API → Shared contracts: validates against
- HTTP API → Campus identity: dispatches
- HTTP API → Listings and search: dispatches
- HTTP API → Media uploads: dispatches
- HTTP API → Content moderation: dispatches
- HTTP API → Wish wall: dispatches
- HTTP API → In-app notifications: dispatches
- HTTP API → Chat and realtime: dispatches
- HTTP API → WebSocket hub: mounts
- HTTP API → Meetup transactions: dispatches
- HTTP API → Profiles: dispatches
- HTTP API → Admin governance: mounts
- HTTP API → PostgreSQL: reads and writes
- Job worker → Match jobs: runs jobs
- Match jobs → PostgreSQL: reads and writes
- Match jobs → In-app notifications: creates notifications
- Media uploads → S3 storage: presigns and verifies
- Listings and search → PostgreSQL: reads and writes
- Wish wall → PostgreSQL: reads and writes
- Campus identity → PostgreSQL: reads and writes
- Chat and realtime → PostgreSQL: reads and writes
- Chat and realtime → WebSocket hub: publishes events
- Meetup transactions → PostgreSQL: reads and writes
- Meetup transactions → Chat and realtime: writes system messages
- In-app notifications → PostgreSQL: reads and writes
- Profiles → PostgreSQL: reads
- Admin governance → PostgreSQL: reads and writes