TideAI

简体中文 | English

See where the AI tide is heading.

TideAI is an interactive technology trend map for developers and AI enthusiasts. It continuously collects public signals from GitHub repositories and Hugging Face models, then turns real growth over 24 hours, 7 days, and 30 days into an explorable pixel-art wave instead of a conventional leaderboard.

At a glance, users can see which projects are gaining momentum, how strong their growth is, and whether they sit at the crest, in the body, or beneath the current. Every detail card links directly to the corresponding GitHub repository or Hugging Face model page.

Preview

Highlights

• Real data sources — collects stars, forks, likes, downloads, and other public metrics through the GitHub REST API and Hugging Face API.
• Explainable ranking — GitHub repositories rank by stars gained within the selected window; Hugging Face models rank by likes gained. Total counts are only used as tie-breakers.
• Multiple time windows — switch between 24h, 7d, and 30d trends and view the Top 10 for each source.
• Automatic discovery — expands the candidate pool with OSS Insight, GitHub Search, and Hugging Face Trending while preserving curated seeds.
• Scheduled collection — the long-running scheduler saves a snapshot every day and discovers new candidates every week by default.
• Interactive wave map — a Canvas 2D pixel wave carries trend signals, while the sidebar and detail card expose rankings, growth, totals, and categories.

How it works

Curated seeds + trend discovery
              ↓
    GitHub / Hugging Face APIs
              ↓
     Daily cumulative snapshots
              ↓
Window growth (current - historical baseline)
              ↓
       Top 10 API → Canvas wave map

Changing the time window does not trigger a live scrape. The backend computes rankings from accumulated snapshots, keeping requests fast, stable, and reproducible.

Tech stack

• Frontend: React 19, TypeScript, Vite, Canvas 2D
• Backend: Python 3.12, FastAPI, Pydantic, SQLAlchemy, Alembic
• Data: SQLite for local and single-server deployment; PostgreSQL-compatible through the database URL
• Collection: HTTPX, GitHub REST API, Hugging Face API
• Verification: Pytest, TypeScript, and Vite production builds

Quick start with real data

1. Start the backend and scheduler

cd backend
uv sync --extra dev
Copy-Item .env.example .env

Edit backend/.env. A GitHub token is recommended for production or long-running collection:

GITHUB_TOKEN=github_pat_your_token
HF_TOKEN=

Initialize the database and start the API with the scheduler:

uv run alembic upgrade head
uv run tideai seed
.\scripts\run-server.ps1

The script starts:

• API: http://localhost:8000
• OpenAPI docs: http://localhost:8000/docs
• Scheduler: runs immediately, then collects every 24 hours and discovers candidates every 7 days

You can also run the two long-lived processes separately:

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
uv run tideai schedule

2. Start the frontend

In another terminal:

cd frontend
Copy-Item .env.example .env.local
npm ci
npm run dev

Open http://localhost:5173. By default, the frontend calls the real API at http://localhost:8000/api/v1/trend-snapshot.

A new database needs at least two collection runs before growth can be calculated. Complete 7-day and 30-day trends require the corresponding amount of snapshot history.

API examples

GET /api/v1/trend-snapshot?source=github&window=24h
GET /api/v1/trend-snapshot?source=hugging_face&window=7d
GET /health

The trend endpoint returns at most 10 items. See docs/api/trend-snapshot.md for the response contract.

Project structure

TideAI/
├── frontend/          # React UI, Canvas wave map, and API client
├── backend/           # FastAPI, collectors, trend service, scheduler, database
├── data/seeds/        # Curated initial candidates
├── data/snapshots/    # Local demonstration history
├── docs/              # Product, API, architecture, and requirement documents
└── prototype/         # Early visual prototype

Verification

cd backend
uv run pytest

cd ../frontend
npm run build

See backend/README.md for detailed collection, configuration, and scheduling instructions. Product scope and scoring design are documented in docs/mvp.md.