聽播客 ｜ TinBoker

Taiwanese stock & podcast intelligence. Browse TW/US stocks, follow market topics, and discover AI-summarized financial podcasts.

Live: tinboker.com

---

What is TinBoker?

TinBoker (聽播客) is a financial intelligence platform for the Taiwanese market. It pairs a real-time stock dashboard (TW + US markets) with an AI content pipeline that ingests financial podcasts and news, derives transcripts, summaries, ticker sentiment, and an entity/topic knowledge graph, then surfaces it through a Traditional-Chinese web UI.

This repository is a monorepo consolidating what used to be two separate projects — the platform (tinboker-platform) and the content/agent pipelines (tinboker-agents) — into one standalone repo.

Tier	Path	What it is	Runs on
Web UI	frontend/	React 19 + Vite SPA (Traditional Chinese)	Cloudflare Pages → tinboker.com
Platform API	backend/	FastAPI app — stocks, search, graphs, auth, podcasts	Docker on Netcup VPS
Content pipelines	pipelines/	Podcast + news ingestion → summaries, ticker sentiment, wiki graph	systemd on VPS
MCP servers	mcp-servers/	Agent tooling (stock translations, article authoring, podcast regeneration)	uvx / uv, stdio

---

Features

• Stock dashboard — price charts and key statistics for TW + US markets
• Market topics and sectors — connect podcast coverage with stocks and market themes
• Podcast intelligence — AI-summarized financial podcasts with per-episode ticker sentiment
• News & wiki — ingested market news folded into an entity/topic knowledge base
• Full-text search with autocomplete and trending tickers/tags
• Real-time price feed over WebSocket (FinMind + Massive)
• Google OAuth authentication, watchlists, and an admin/config control plane
• PWA — installable, offline-aware, with light/dark theming

---

Architecture

                         Browser  /  PWA
                              │
                              ▼
              Cloudflare Pages (static SPA)            ← frontend/  (React 19 + Vite)
                              │
                              ▼
              Cloudflare Proxy (DDoS + CDN cache)
                              │
                              ▼
              Netcup VPS — Caddy (reverse proxy + auto-HTTPS)
        ┌─────────────────────┼───────────────────────────────┐
        │                     │                                │
   :8000/:8001/:8002     :8003 (podcast)                  systemd timer
   Platform API          /api/wiki, /api/podcast          news ingestion
   (backend/)            (pipelines/services/podcast)      (pipelines/services/news)
        │                     │                                │
        └─────────────────────┴────────────────┬───────────────┘
                              │                 │
                       Docker Compose      Spotify RSS · Tavily/RSS news
                       ├── FastAPI               │
                       ├── PostgreSQL            ▼  transcribe → summarize → extract
                       ├── Redis             VPS media disk (/srv/tinboker-media)
                       └── Netdata               │
                              │                   │
                              └──── content in PostgreSQL ────┘

                    GCP Secret Manager — credentials only

Data direction: the content pipelines derive content and write to the shared VPS PostgreSQL database and media disk. The platform API serves that content over HTTP. Firestore, Cloud SQL, and GCS have been retired.

---

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript 5.9, Vite 7, Tailwind CSS 4
Charts	TradingView Lightweight Charts, D3.js, Nivo
State / routing	Zustand 5, React Router 7
Validation	Zod 4
Backend	FastAPI 0.104, Python 3.12, Pydantic v2
ORM / cache	SQLAlchemy 2 (SQLite dev / PostgreSQL prod), Redis 7 (hiredis)
Auth	Google OAuth → JWT (python-jose)
Pipelines	uv workspaces, LangGraph content builder, Marp slides, Spotify/Tavily ingestion
Data APIs	Massive API (US stocks), FinMind (TW stocks), Spotify and Tavily (content ingestion)
Infra	Docker, Caddy, Netcup VPS, GitHub Actions, Cloudflare

---

Repository Layout

tinboker/
├── frontend/            React 19 + Vite web UI        → Cloudflare Pages (tinboker.com)
├── backend/             FastAPI platform API           → Docker on VPS
├── pipelines/           Content & agent pipelines (podcast + news ingestion, wiki builder)
├── mcp-servers/         MCP launchers for stock translations, article authoring, podcast regeneration
├── docs/                Domain references, workflows, data contracts, runbooks
├── scripts/             Local maintenance utilities
├── tests/               Root maintenance-script tests
├── .claude/             Claude Code subagents + skills (thin wrappers → docs/)
├── .codex/              Codex agents + MCP config
├── .agents/             Shared skill directory link
├── .github/workflows/   CI/CD (backend, frontend, pipelines)
├── CLAUDE.md            Root AI-agent context  (AGENTS.md → symlink)
└── README.md

backend/src/
├── main.py          FastAPI app & lifespan
├── config.py        Settings (env + GCP Secret Manager)
├── routers/         API endpoint modules (stocks, search, podcast, admin_*, …)
├── services/        Business logic (stock, finmind, massive, insight, …)
├── database/        ORM models & CRUD
├── models/ schemas/ Pydantic request/response models
├── auth/            Google OAuth + JWT
├── cache/           Redis client
├── middleware/      Request middleware
├── workers/         Background tasks & cron jobs
└── utils/           Shared helpers

frontend/src/
├── pages/           Route-level React pages
├── components/      Reusable UI (charts, stock, graph, financial, industry, …)
├── services/        API client + business logic
├── store/           Zustand state stores
├── schemas/ validation/   Zod schemas for API responses
├── hooks/ lib/ utils/     Hooks and helpers
├── types/           TypeScript type definitions
└── assets/          SVG icon system (no emoji icons)

pipelines/
├── services/
│   ├── podcast/     Spotify RSS → download → transcribe → summarize → Postgres + VPS media; serves /api/wiki (:8003)
│   └── news/        Tavily/RSS news → resolve tickers → ingest (systemd timer)
├── libs/shared/     Shared pipeline utilities and wiki_builder (Postgres-backed)
├── scripts/         seeding & ops scripts
└── docs/            wiki schema, content-api roadmap, data-consolidation plan, MIGRATION runbook

---

Local Development

Prerequisites: Python 3.12+ with uv, Node 20+, Docker (for Redis).

Backend — platform API

cd backend
cp .env.example .env          # fill in API keys
uv sync                       # install Python deps
docker compose up -d redis    # start Redis
python -m src.main            # → localhost:5174  (docs at /docs)

Frontend — web UI

cd frontend
npm install
npm run dev                   # → localhost:5173

To use the local backend, set VITE_API_BASE_URL=http://localhost:5174 in frontend/.env.local.

Pipelines — content ingestion

cd pipelines
uv sync                                          # install workspace deps
cd services/podcast && python main.py --config podcasts_tw.json

Pipelines are infra/content-only — no UI lives here. See pipelines/AGENTS.md.

---

Environments

Environment	Access	Trigger
Production	tinboker.com	v* tag on main
Staging	Internal	merge to main
Dev	Internal	merge to develop
Local	localhost:5173 / localhost:5174	manual

Internal routing and host details are in docs/infra-runbook.md.

---

CI/CD

Pipeline	Trigger	Effect
backend-ci.yml	PR → develop/main	Lint (ruff) + pytest, gated by a ci-gate job
backend-deploy.yml	Push → develop/main, v* tag	Docker build → VPS deploy → Cloudflare purge
backend-deploy-admin.yml	Manual (workflow_dispatch)	Deploy the admin-dashboard image variant (optionally with Netdata)
frontend-ci.yml	PR → develop/main	TypeScript check + ESLint
frontend-deploy.yml	Push → develop/main, v* tag	Cloudflare Pages deploy → CDN purge
pipelines-ci.yml	PR → develop/main	Lint + pytest (uv workspace)
pipelines-deploy.yml	Push → develop/main	Deploy pipelines services to VPS
backend-health-check.yml	Cron (10 min)	Health check all envs
refresh-social-tokens.yml	Cron (monthly) + manual	Refresh the Threads access token in GCP Secret Manager

Docker images: ghcr.io/haoweichan/tinboker-backend:{tag}. Deploys flow strictly through Git → PR → CI/CD — never SSH/rsync to the VPS directly. See docs/workflows/deploy-flow.md.

---

Testing

# Backend — all tests (or unit-only, or with coverage)
cd backend && pytest tests/ -v
cd backend && pytest tests/unit/ -v
cd backend && pytest tests/ -v --cov=src --cov-report=term-missing

# Pipelines — per-package (uv workspace)
cd pipelines && uv run --package tinboker-podcast pytest
cd pipelines && uv run --package tinboker-shared  pytest

# Frontend — type check + build, and lint
cd frontend && npm run build
cd frontend && npm run lint

# Root maintenance scripts
cd backend && uv run --python 3.12 pytest ../tests/

The root tests cover maintenance scripts and use the backend's test dependencies.

End-to-end and environment-specific QA: docs/agents/qa-tester.md.

---

Working with AI agents

This repo is set up for AI coding tools across vendors. All configs are thin wrappers that point at the tool-neutral domain docs in docs/agents/, so guidance stays in one place:

• Claude Code — subagents in .claude/agents/, skills in .claude/skills/
• Codex — agents in .codex/agents/, MCP servers in .codex/config.toml
• Shared skills — .agents/skills/ points to the Claude skill directory
• Root context — CLAUDE.md (symlinked as AGENTS.md), plus backend/AGENTS.md, frontend/AGENTS.md, and pipelines/AGENTS.md

---

Contributing

1. Branch from develop: git checkout -b feat/your-feature develop
2. Open a PR targeting develop — CI must pass
3. Merge to develop auto-deploys to dev; promote via develop → main (staging), then tag v* (production)

See CLAUDE.md for agent guidelines and docs/infra-runbook.md for the infrastructure runbook.

---

License

Proprietary — all rights reserved. The code is publicly visible for reference only and is not licensed for reuse. See LICENSE.