JavaInfoHunter

• Dashboard - Overview with KPIs, trending topics, and key metrics
• Trends - Interactive time-series charts powered by Recharts
• Knowledge Graph - Force-directed visualization using D3.js
• News Browser - Advanced data grid with filtering, sorting, and search

• Sources Management - CRUD operations for RSS feed sources
• Agent Monitoring - Real-time agent execution tracking and statistics
• System Status - Health monitoring, resource usage, and crawl triggers

• Sentiment analysis (POSITIVE, NEGATIVE, NEUTRAL)
• Category-based news filtering
• Similar article discovery
• Full-text search across news articles
• Manual and scheduled crawl triggers

• Node.js 18.x or higher
• npm 9.x or higher
• Backend API running on http://localhost:8080

1. Clone the repository

git clone <repository-url>
cd JavaInfoHunter

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the project root:

VITE_API_URL=http://localhost:8080/api/v1

4. Start the development server

npm run dev

The application will be available at http://localhost:5173

src/
├── modules/                    # Feature-based modules
│   ├── research/              # Research & Analytics features
│   │   ├── dashboard/         # KPI overview page
│   │   ├── trends/            # Time-series trend charts
│   │   ├── knowledge/         # D3.js knowledge graph
│   │   └── news/              # News data grid with filters
│   └── admin/                 # System administration
│       ├── sources/           # RSS source management
│       ├── agents/            # Agent monitoring
│       └── system/            # System health & status
├── shared/                    # Shared application code
│   ├── api/                   # API layer
│   │   ├── client.ts          # Axios instance with interceptors
│   │   ├── endpoints.ts       # Typed API endpoints
│   │   └── types.ts           # TypeScript API types
│   ├── components/            # Reusable components
│   │   ├── ui/                # shadcn/ui components
│   │   ├── layout/            # Layout components (MainLayout)
│   │   └── data-display/      # Display components (StatCard)
│   ├── hooks/                 # React Query hooks
│   ├── stores/                # Zustand state stores
│   ├── lib/                   # Utilities (cn, logger, date)
│   └── constants/             # App constants
├── App.tsx                    # Route configuration
└── main.tsx                   # Application entry point

The project uses path aliases configured in both tsconfig.json and vite.config.ts:

New Route

// App.tsx - Add lazy import and route
const NewFeature = lazy(() => import('./modules/new-feature'));
<Route path="/new-feature" element={<MainLayout><NewFeature /></MainLayout>} />

New API Call

// src/shared/api/endpoints.ts
export const myApi = {
  getData: (): ApiData<ApiResponse<MyType>> => apiClient.get('/endpoint'),
};

New UI Component

npx shadcn@latest add {component}

New Query Hook

// src/shared/hooks/useMyData.ts
export function useMyData() {
  return useQuery({
    queryKey: ['my-data'],
    queryFn: () => myApi.getData(),
  });
}

The application uses Axios with a configured client in src/shared/api/client.ts:

• Base URL: Configured via VITE_API_URL environment variable
• Timeout: 30 seconds
• Response interceptor: Automatically unwraps data and shows toast errors

All API responses follow this structure:

interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
  timestamp?: string;
}

The application uses a dual state management approach:

Server State (React Query) - All API data fetched with @tanstack/react-query

• Custom hooks in src/shared/hooks/
• Automatic caching, refetching, and background updates

UI State (Zustand) - Local component state managed in src/shared/stores/app-store.ts

• Active module selection
• News filters
• Selected news item
• Sidebar collapse state

npm run build

The production build will be output to the dist/ directory. The build process:

1. Runs TypeScript type checking
2. Bundles and minifies with Vite
3. Optimizes for production deployment

To preview the production build:

npm run preview

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow existing code patterns and conventions
• Use immutable patterns (create new objects, don't mutate)
• Keep functions small (< 50 lines)
• Keep files focused (< 800 lines)
• Handle errors explicitly at every level
• Use TypeScript strict mode features

Follow conventional commits:

<type>: <description>

Types: feat, fix, refactor, docs, test, chore, perf, ci

This project is licensed under the MIT License - see the LICENSE file for details.

Backend API Documentation: Refer to the backend repository for full API specification and WebSocket event details.