IdolTracker Frontend

IdolTracker Frontend is the React/TypeScript web interface for IdolTracker, a news aggregation MVP focused on discovering, filtering, and reading processed idol-related article coverage.

The frontend presents backend-processed article data through a coverage feed, route-based entity views, search, filters, pagination, and a two-pane master-detail reading experience.

Project status: MVP / portfolio project. This repository contains the frontend application. A compatible backend API is required for live article data.

---

Table of Contents

• Overview
• Features
• Tech Stack
• Repository Structure
• Getting Started
• Environment Variables
• Available Scripts
• API Contract
• Public Release Notes
• License

---

Overview

IdolTracker Frontend is designed around a simple product workflow: users can browse processed article coverage, search across content, narrow results with filters, and open individual articles without losing their place in the feed.

The app includes views for:

• Main article coverage feed
• Artist-scoped article views
• Group-scoped article views
• Source-scoped article views

The current frontend focuses on the reading, discovery, and filtering experience. It expects the backend to provide processed article records through /api/content.

---

Features

Article discovery feed

• Fetches processed articles from the backend
• Displays article cards with publication/source metadata
• Supports loading, empty, and error states
• Uses pagination through limit and skip query parameters

Search

• Searches processed article content through the backend API
• Debounces user input before querying
• Keeps the article feed responsive while search state changes

Filters

• Filter by sentiment
• Filter by language
• Filter by country
• Reset active filters
• Persist selected filters locally between sessions

Entity views

• Artist route: /artists/:id
• Group route: /groups/:id
• Source route: /sources/:id

Master-detail reading experience

• Keeps the article list visible while showing selected article details
• Supports focused reading without losing feed context
• Handles empty detail state when no article is selected

---

Tech Stack

• React
• TypeScript
• Vite
• TanStack Query
• React Router DOM
• Zustand
• Tailwind CSS
• ESLint

---

Repository Structure

IdolTrackerFrontend_Main/
├── public/             # Static assets
├── src/
│   ├── api/            # Backend API client and shared API types
│   ├── components/     # Reusable UI components
│   ├── pages/          # Route-level views
│   ├── App.tsx         # Application routes and providers
│   └── main.tsx        # React entry point
├── .env.example        # Example environment variables
├── package.json
└── README.md

---

Getting Started

Prerequisites

Install:

• Node.js 20+
• npm
• A compatible IdolTracker backend running locally or remotely

Installation

npm install

Configure environment

Copy the example environment file:

cp .env.example .env

Set the backend API base URL:

VITE_API_BASE_URL=http://localhost:8000

Run the development server

npm run dev

The Vite dev server will print the local frontend URL, usually:

http://localhost:5173

---

Environment Variables

Variable	Description	Example
VITE_API_BASE_URL	Base URL for the backend API	http://localhost:8000

Only variables prefixed with VITE_ are exposed to the frontend by Vite.

---

Available Scripts

npm run dev

Starts the local Vite development server.

npm run build

Runs TypeScript build checks and creates a production build.

npm run lint

Runs ESLint.

npm run preview

Previews the production build locally.

---

API Contract

The frontend expects a backend API that exposes:

GET /api/content

Supported query parameters:

Parameter	Description
limit	Maximum number of articles to return
skip	Number of articles to skip for pagination
search	Search query for article discovery

Expected response shape:

type ApiArticle = {
  id?: string | number;
  title?: string;
  source?: string;
  url?: string;
  published_at?: string;
  sentiment?: string;
  language?: string;
  country?: string;
  artists?: string[];
  groups?: string[];
  summary?: string;
  content?: string;
};

The frontend is defensive around response handling and expects /api/content to return an array of article-like objects.

---

Public Release Notes

Before publishing or linking this repository publicly, confirm that:

• No private API URLs, credentials, or secrets are committed
• Demo screenshots use safe/non-sensitive data
• Backend deployment details are not exposed accidentally
• The README reflects the current frontend scope accurately
• The repository license has been approved by the project team

---

License

This project is licensed under the MIT License.

See LICENSE for details.