mirror of
https://github.com/kjanat/livedash-node.git
synced 2026-01-16 13:12:10 +01:00
129 lines
4.8 KiB
Markdown
129 lines
4.8 KiB
Markdown
# LiveDash-Node AGENTS.md
|
|
|
|
This document provides a comprehensive overview of the LiveDash-Node project, including its architecture, key components, and operational procedures.
|
|
|
|
## Project Overview
|
|
|
|
LiveDash-Node is a multi-tenant dashboard system designed for tracking and analyzing chat session metrics. It provides a web-based interface for users to monitor key performance indicators, review chat transcripts, and gain insights into customer interactions. The system is built with a modern technology stack, featuring a Next.js frontend, a Node.js backend, and a Prisma ORM for database interactions.
|
|
|
|
### Core Features
|
|
|
|
- **Multi-tenant architecture:** Supports multiple companies, each with its own isolated data and dashboard configurations.
|
|
- **Automated data fetching:** Periodically fetches chat session data from external CSV files.
|
|
- **Data processing and analysis:** Parses and enriches raw session data, calculating metrics such as sentiment, response times, and token usage.
|
|
- **Interactive dashboards:** Visualizes key metrics through a variety of charts and graphs, including geographic maps, donut charts, and time-series data.
|
|
- **Session-level details:** Allows users to drill down into individual chat sessions to view full transcripts and detailed metadata.
|
|
- **User authentication and authorization:** Implements a secure login system with role-based access control.
|
|
|
|
## Technical Architecture
|
|
|
|
The application is a full-stack TypeScript project built on the Next.js framework. It uses a custom server to integrate scheduled tasks for data fetching and processing.
|
|
|
|
### Technology Stack
|
|
|
|
- **Frontend:**
|
|
- Next.js (React framework)
|
|
- TypeScript
|
|
- Tailwind CSS (styling)
|
|
- Chart.js, D3.js (data visualization)
|
|
- Leaflet.js (maps)
|
|
- **Backend:**
|
|
- Node.js
|
|
- Next.js API Routes
|
|
- Prisma (ORM)
|
|
- SQLite (database)
|
|
- **Authentication:**
|
|
- NextAuth.js
|
|
- **Testing:**
|
|
- Playwright (end-to-end testing)
|
|
- **Linting and Formatting:**
|
|
- ESLint
|
|
- Prettier
|
|
- markdownlint
|
|
|
|
### Project Structure
|
|
|
|
The project is organized into the following key directories:
|
|
|
|
- `app/`: Contains the main application code, including pages, layouts, and UI components.
|
|
- `components/`: Reusable React components used throughout the application.
|
|
- `lib/`: Core application logic, including data fetching, processing, and utility functions.
|
|
- `pages/api/`: Next.js API routes for handling backend requests.
|
|
- `prisma/`: Database schema, migrations, and seed scripts.
|
|
- `public/`: Static assets such as images and fonts.
|
|
- `scripts/`: Standalone scripts for various development and operational tasks.
|
|
|
|
## Key Components
|
|
|
|
### Data Fetching and Processing
|
|
|
|
The system uses a two-stage process for handling chat session data:
|
|
|
|
1. **Fetching:** The `lib/scheduler.ts` module defines a cron job that periodically fetches new session data from a CSV file specified for each company.
|
|
2. **Processing:** The `lib/processingScheduler.ts` module defines a second cron job that processes the fetched data. This includes:
|
|
- Parsing the CSV data.
|
|
- Enriching the data with additional information (e.g., sentiment analysis, geographic location).
|
|
- Storing the processed data in the database.
|
|
|
|
### Database Schema
|
|
|
|
The database schema is defined in `prisma/schema.prisma` and consists of the following models:
|
|
|
|
- `Company`: Represents a tenant in the system.
|
|
- `User`: Represents a user with access to the system.
|
|
- `Session`: Represents a single chat session.
|
|
- `Message`: Represents a single message within a chat session.
|
|
|
|
### API Endpoints
|
|
|
|
The application exposes a set of API endpoints for handling various client-side requests. These are defined in the `pages/api/` directory and include endpoints for:
|
|
|
|
- User authentication (login, registration, password reset).
|
|
- Dashboard data (metrics, sessions, users).
|
|
- Administrative tasks (triggering data processing).
|
|
|
|
## Operational Procedures
|
|
|
|
### Local Development
|
|
|
|
To run the application in a local development environment, follow these steps:
|
|
|
|
1. Install the dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
2. Initialize the database:
|
|
```bash
|
|
npx prisma migrate dev
|
|
npx prisma db seed
|
|
```
|
|
3. Start the development server:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Running with Schedulers
|
|
|
|
To run the development server with the data fetching and processing schedulers enabled, use the following command:
|
|
|
|
```bash
|
|
npm run dev:with-schedulers
|
|
```
|
|
|
|
### Linting and Formatting
|
|
|
|
The project uses ESLint and Prettier for code linting and formatting. The following commands are available:
|
|
|
|
- `npm run lint`: Check for linting errors.
|
|
- `npm run lint:fix`: Automatically fix linting errors.
|
|
- `npm run format`: Format the code using Prettier.
|
|
- `npm run format:check`: Check for formatting errors.
|
|
|
|
### Testing
|
|
|
|
The project uses Playwright for end-to-end testing. To run the tests, use the following command:
|
|
|
|
```bash
|
|
npx playwright test
|
|
```
|