Advice Atlas

A full-stack starter project for visualizing podcast advice quotes.

Stack

• Frontend: Next.js, TypeScript, Tailwind CSS, shadcn-style components, Recharts, ECharts, TanStack Query, Zustand
• Backend: FastAPI, uv, Polars, Pydantic
• Cache: in-memory cache by default, optional Redis
• Dataset: small CSV file stored inside the backend folder

Folder structure

advice-atlas/
├── apps/
│   ├── web/                 # Next.js frontend
│   └── api/                 # FastAPI backend
│       └── data/
│           └── podcast_advice.csv
├── data/raw/                # optional monorepo copy of raw data
├── docker-compose.yml       # optional Redis
├── package.json
└── pnpm-workspace.yaml

1. Install tools

Install pnpm and uv first.

npm install -g pnpm

For uv, use the official installer for your system, then check:

uv --version

2. Install frontend dependencies

From the root:

pnpm install

3. Install backend dependencies

cd apps/api
uv sync
cd ../..

4. Environment files

Create frontend env:

cp apps/web/.env.example apps/web/.env.local

Create backend env:

cp apps/api/.env.example apps/api/.env

5. Run everything

From the root:

pnpm dev

Open:

Frontend: http://localhost:3000
Backend docs: http://localhost:8000/docs

Replacing the dataset

Put your real CSV here:

apps/api/data/podcast_advice.csv

Then edit:

apps/api/.env

Example:

DATASET_PATH=data/podcast_advice.csv
GUEST_COLUMN=Guest Experience / Expert Field
QUOTE_COLUMN=Advice to Young People
CACHE_BACKEND=memory

The column names must exactly match your CSV headers.

Redis is optional

For a KB-sized dataset, keep this:

CACHE_BACKEND=memory

To test Redis later:

docker compose up -d redis

Then change backend .env:

CACHE_BACKEND=redis
REDIS_URL=redis://localhost:6379/0

Important endpoints

GET /api/quotes
GET /api/analytics/overview
GET /api/analytics/themes
GET /api/analytics/tones
GET /api/analytics/experts
GET /api/analytics/keywords
GET /api/analytics/theme-expert
GET /api/analytics/treemap
GET /api/analytics/quote-map
GET /api/analytics/network
POST /api/admin/reload

What to customize next

1. Replace the sample CSV with your real dataset.
2. Improve THEME_KEYWORDS in apps/api/app/data_loader.py.
3. Add real embedding-based semantic search.
4. Add a database only if the dataset becomes bigger.
5. Add Redis only after the app is working.