mirror of https://github.com/buster-so/buster.git
naming conventions
This commit is contained in:
Nate Kelley
parent
c6ac866d72
commit
d98bd17741
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
description: Rules for how the buster_socket api directory shoudl function
|
||||
globs: src/api/buster_socket/**/*
|
||||
---
|
||||
# API Structure Rules
|
||||
|
||||
## Directory Structure
|
||||
Each API namespace should follow this specific structure:
|
||||
|
||||
```
|
||||
src/api/{namespace}/
|
||||
├── {namespace}Requests.ts # Contains all request interfaces and types
|
||||
├── {namespace}Responses.ts # Contains all response interfaces and types
|
||||
└── index.ts # Exports all public interfaces and functions
|
||||
```
|
||||
|
||||
## File Requirements
|
||||
|
||||
### {namespace}Requests.ts
|
||||
- Must contain all request interfaces and types for the namespace
|
||||
- Each request interface should be prefixed with the namespace
|
||||
- Example: `interface UserCreateRequest { ... }`
|
||||
- Must include proper TypeScript types and documentation
|
||||
|
||||
### {namespace}Responses.ts
|
||||
- Must contain all response interfaces and types for the namespace
|
||||
- Each response interface should be prefixed with the namespace
|
||||
- Example: `interface UserCreateResponse { ... }`
|
||||
- Must include proper TypeScript types and documentation
|
||||
|
||||
### index.ts
|
||||
- Must export all public interfaces, types, and functions
|
||||
- Should re-export from both requests and responses files
|
||||
- Should contain any namespace-specific utility functions
|
||||
- Must use named exports (no default exports)
|
||||
|
||||
## Naming Conventions
|
||||
- All file names must use PascalCase for namespace names
|
||||
- All interface names must be prefixed with the namespace
|
||||
- All type names must be prefixed with the namespace
|
||||
- Use descriptive names that clearly indicate purpose
|
||||
|
||||
## Documentation Requirements
|
||||
- Each interface must have JSDoc comments explaining its purpose
|
||||
- Each property in interfaces must be documented
|
||||
- Include examples where appropriate
|
||||
- Document any validation requirements or constraints
|
||||
|
||||
## Type Safety
|
||||
- Avoid using `any` type. We should NEVER use any types.
|
||||
- Use strict TypeScript configurations
|
||||
- Define proper type guards when necessary
|
||||
- Use generics appropriately for reusable types
|
||||
|
||||
## Example Structure
|
||||
```typescript
|
||||
// {namespace}Requests.ts
|
||||
export interface {Namespace}CreateRequest {
|
||||
// properties
|
||||
}
|
||||
|
||||
// {namespace}Responses.ts
|
||||
export interface {Namespace}CreateResponse {
|
||||
// properties
|
||||
}
|
||||
|
||||
// index.ts
|
||||
export * from './{namespace}Requests';
|
||||
export * from './{namespace}Responses';
|
||||
```
|
||||
|
||||
## Additional Guidelines
|
||||
1. Keep files focused and single-responsibility
|
||||
2. Use TypeScript's strict mode
|
||||
3. Implement proper error handling types
|
||||
4. Follow consistent formatting
|
||||
5. Include proper type exports
|
||||
6. Maintain backward compatibility
|
||||
7. Use enums for fixed sets of values
|
||||
192
web/README.md
192
web/README.md
|
|
@ -1,32 +1,196 @@
|
|||
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
|
||||
# Buster Web Application
|
||||
|
||||
## Project Overview
|
||||
This is a modern web application built with Next.js 14+, utilizing the App Router architecture. The application is structured to provide a scalable, maintainable, and performant user experience.
|
||||
|
||||
## Project Architecture
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
src/
|
||||
├── api/
|
||||
│ ├── buster_rest/ # REST API integrations
|
||||
│ ├── buster_socket/ # WebSocket implementations
|
||||
│ └── asset_interfaces/# TypeScript interfaces for API responses
|
||||
├── app/ # Next.js App Router directory
|
||||
│ └── app/ # Main application routes
|
||||
│ ├── _components/ # Global components that are route specific and shared across pages
|
||||
│ ├── _controllers/ # Business logic controllers
|
||||
│ ├── _layouts/ # Shared layout components
|
||||
│ ├── (chat_experience)/ # Every page that will require a "chat" experience.
|
||||
│ ├── collections/ # Collections feature
|
||||
│ ├── dashboards/ # Dashboard views
|
||||
│ ├── datasets/ # Dataset management
|
||||
│ ├── logs/ # Metrics (admin view)
|
||||
│ ├── metrics/ # Metrics generated by the user
|
||||
│ ├── new-user/ # New user onboarding
|
||||
│ ├── settings/ # User settings
|
||||
│ └── terms/ # Terms that were defined for all the datasets
|
||||
├── components/ # Reusable React components
|
||||
├── config/ # Application configuration files
|
||||
├── context/ # React Context providers
|
||||
├── hooks/ # Custom React hooks
|
||||
├── middleware/ # Request/response middleware
|
||||
├── routes/ # Application routing logic
|
||||
└── utils/ # Utility functions and helpers
|
||||
```
|
||||
|
||||
## Technical Stack
|
||||
- **Framework**: Next.js 14+ with App Router
|
||||
- **Language**: TypeScript
|
||||
- **State Management**: React Context
|
||||
- **API Integration**: REST and WebSocket
|
||||
- **Styling**: [Your styling solution]
|
||||
|
||||
## Getting Started
|
||||
|
||||
First, run the development server:
|
||||
### Prerequisites
|
||||
- Node.js 18.x or higher
|
||||
- npm or yarn package manager
|
||||
|
||||
### Development Setup
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
# or
|
||||
yarn install
|
||||
```
|
||||
|
||||
3. Run the development server:
|
||||
```bash
|
||||
npm run dev
|
||||
# or
|
||||
yarn dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
bun dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
The application will be available at [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
||||
## Key Features
|
||||
- Real-time communication via WebSocket
|
||||
- REST API integration
|
||||
- Centralized state management using Context
|
||||
- Component-based architecture
|
||||
- Type-safe development with TypeScript
|
||||
|
||||
This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
|
||||
## Project Structure Details
|
||||
|
||||
## Markdown Components
|
||||
### API Layer (`src/api/`)
|
||||
- `buster_rest/`: REST API implementations for various features
|
||||
- `buster_socket/`: WebSocket implementations for real-time features
|
||||
- `asset_interfaces/`: TypeScript interfaces defining API response structures
|
||||
|
||||
For information about custom Markdown components supported in this project, please refer to the [AppMarkdown Components documentation](src/components/text/AppMarkdown/Readme.md).
|
||||
### Components (`src/components/`)
|
||||
Reusable React components organized by feature or functionality.
|
||||
|
||||
### Config (`src/config/`)
|
||||
Configuration files and environment-specific settings:
|
||||
- Environment variables management
|
||||
- Feature flags
|
||||
- API endpoints configuration
|
||||
- Application-wide constants
|
||||
|
||||
## Deploy on Vercel
|
||||
### Context (`src/context/`)
|
||||
Global state management using React Context, including:
|
||||
- Metrics tracking
|
||||
- Application-wide state management
|
||||
- Individual metric providers
|
||||
|
||||
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
||||
### Hooks (`src/hooks/`)
|
||||
Custom React hooks that encapsulate reusable stateful logic:
|
||||
- Data fetching hooks
|
||||
- State management hooks
|
||||
- Utility hooks for common functionality
|
||||
- Feature-specific hooks
|
||||
|
||||
### Middleware (`src/middleware/`)
|
||||
Request/response middleware handlers:
|
||||
- Authentication middleware
|
||||
- Request validation
|
||||
- Response transformation
|
||||
- Error handling middleware
|
||||
|
||||
### Routes (`src/routes/`)
|
||||
Application routing and page structure:
|
||||
- Route definitions
|
||||
- Page components
|
||||
- Route-specific logic
|
||||
- Navigation configuration
|
||||
|
||||
### Utils (`src/utils/`)
|
||||
Helper functions and utilities used across the application.
|
||||
|
||||
### App Router Architecture (`src/app/`)
|
||||
The application uses Next.js 14+ App Router, following a feature-first organization within the `app` directory:
|
||||
|
||||
#### Core Structure
|
||||
- `_components/`: Route-specific shared components that are used across multiple pages within the app
|
||||
- `_controllers/`: Business logic controllers that handle data flow and state management
|
||||
- `_layouts/`: Shared layout components for consistent page structure
|
||||
|
||||
#### Feature Organization
|
||||
- `(chat_experience)/`: Grouped chat-related features (using route groups)
|
||||
- Isolated chat functionality
|
||||
- Real-time messaging components
|
||||
- Chat-specific layouts
|
||||
|
||||
#### Main Features
|
||||
- `collections/`: Management and display of user collections
|
||||
- `dashboards/`: Data visualization and analytics dashboards
|
||||
- `datasets/`: Dataset creation, management, and analysis tools
|
||||
- `logs/`: System and user activity logging interface
|
||||
- `metrics/`: Performance and usage metrics visualization
|
||||
- `new-user/`: User onboarding flow and initial setup
|
||||
- `settings/`: User preferences and application configuration
|
||||
- `terms/`: Legal documentation and user agreements
|
||||
|
||||
#### Layout Structure
|
||||
- `layout.tsx`: Root layout component providing common UI elements
|
||||
- `layoutClient.tsx`: Client-side layout components for dynamic features
|
||||
- `page.tsx`: Main entry point for each route
|
||||
|
||||
This organization follows Next.js best practices for:
|
||||
- Route Groups and Layouts
|
||||
- Server and Client Components
|
||||
- Colocation of Related Features
|
||||
- Parallel Routes and Intercepted Routes
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Style
|
||||
- Use functional components with hooks
|
||||
- Follow TypeScript best practices
|
||||
- Maintain consistent naming conventions
|
||||
- Write clean, self-documenting code
|
||||
|
||||
### Component Development
|
||||
- Create reusable components
|
||||
- Implement proper prop typing
|
||||
- Follow the single responsibility principle
|
||||
|
||||
### State Management
|
||||
- Use React Context for global state
|
||||
- Implement proper error boundaries
|
||||
- Handle loading states appropriately
|
||||
|
||||
## Deployment
|
||||
The application can be deployed using various platforms:
|
||||
|
||||
1. **Vercel** (Recommended):
|
||||
- Automatic deployments with Git integration
|
||||
- Built-in performance optimization
|
||||
- Zero-configuration setup
|
||||
|
||||
2. **Manual Deployment**:
|
||||
- Build the application:
|
||||
```bash
|
||||
npm run build
|
||||
# or
|
||||
yarn build
|
||||
```
|
||||
- Start the production server:
|
||||
```bash
|
||||
npm start
|
||||
# or
|
||||
yarn start
|
||||
```
|
||||
|
||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
|
||||
|
|
|
|||
|
|
@ -17,14 +17,27 @@ export type ChatList_getChatsList = {
|
|||
onError?: (d: unknown | RustApiError) => void;
|
||||
};
|
||||
|
||||
/**
|
||||
* Response type for getting a single chat's details.
|
||||
* This response is triggered when requesting a specific chat's information.
|
||||
*/
|
||||
export type Chat_getChat = {
|
||||
/** The route identifier for getting a single chat */
|
||||
route: '/chats/get:getChat';
|
||||
/** Callback function that receives the chat data */
|
||||
callback: (chat: BusterChat) => void;
|
||||
/** Optional error handler for when the chat request fails */
|
||||
onError?: (error: RustApiError) => void;
|
||||
};
|
||||
|
||||
export type Chat_unsubscribe = {
|
||||
route: '/chats/unsubscribe:unsubscribe';
|
||||
callback: (d: { id: string }[]) => void;
|
||||
onError?: (d: unknown | RustApiError) => void;
|
||||
};
|
||||
|
||||
export type Chat_getChat = {
|
||||
route: '/chats/get:getChat';
|
||||
export type Chat_getChatAsset = {
|
||||
route: '/chats/get:getChatAsset';
|
||||
callback: (d: BusterChat) => void;
|
||||
onError?: (d: unknown | RustApiError) => void;
|
||||
};
|
||||
|
|
@ -55,6 +68,7 @@ export type ChatResponseTypes =
|
|||
| ChatList_getChatsList
|
||||
| Chat_unsubscribe
|
||||
| Chat_getChat
|
||||
| Chat_getChatAsset
|
||||
| ChatPost_initializeChat
|
||||
| ChatPost_generatingTitle
|
||||
| ChatPost_generatingMessage;
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
'use client';
|
||||
|
||||
import { ShimmerText, Text } from '@/components/text';
|
||||
import { busterChartsTwMerge } from '@/styles/busterChartsTwMerge';
|
||||
import React from 'react';
|
||||
|
||||
export const PreparingYourRequestLoader: React.FC<{
|
||||
|
|
@ -11,11 +10,7 @@ export const PreparingYourRequestLoader: React.FC<{
|
|||
useShimmer?: boolean;
|
||||
}> = ({ className = '', text = 'Processing your request...', error, useShimmer = true }) => {
|
||||
return (
|
||||
<div
|
||||
className={busterChartsTwMerge(
|
||||
'flex h-full w-full items-center justify-center space-x-1.5',
|
||||
className
|
||||
)}>
|
||||
<div className={`flex h-full w-full items-center justify-center space-x-1.5 ${className}`}>
|
||||
{error || useShimmer === false ? (
|
||||
<Text type="tertiary" className="flex items-center text-center">
|
||||
{/* {!!error && <AppMaterialIcons icon="error" className="mr-1" />} */}
|
||||
|
|
@ -33,9 +28,8 @@ export const NoChartData: React.FC<{
|
|||
className?: string;
|
||||
}> = ({ className = '', noDataText = 'The query ran successfully but didn’t return any data' }) => {
|
||||
return (
|
||||
<div
|
||||
className={busterChartsTwMerge('flex h-full w-full items-center justify-center', className)}>
|
||||
<Text type="tertiary" className={busterChartsTwMerge()}>
|
||||
<div className={`flex h-full w-full items-center justify-center ${className}`}>
|
||||
<Text type="tertiary" className={`${className}`}>
|
||||
{noDataText}
|
||||
</Text>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,39 +0,0 @@
|
|||
import { extendTailwindMerge } from 'tailwind-merge';
|
||||
|
||||
export const busterChartsTwMerge = extendTailwindMerge({
|
||||
override: {
|
||||
classGroups: {
|
||||
/* boxShadow: [
|
||||
{
|
||||
shadow: [
|
||||
{
|
||||
tremor: ['input', 'card', 'dropdown'],
|
||||
'dark-tremor': ['input', 'card', 'dropdown']
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
borderRadius: [
|
||||
{
|
||||
rounded: [
|
||||
{
|
||||
tremor: ['small', 'default', 'full'],
|
||||
'dark-tremor': ['small', 'default', 'full']
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
fontSize: [
|
||||
{
|
||||
text: [
|
||||
{
|
||||
tremor: ['default', 'title', 'metric'],
|
||||
'dark-tremor': ['default', 'title', 'metric']
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
*/
|
||||
}
|
||||
}
|
||||
});
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
import { createStyles } from 'antd-style';
|
||||
|
||||
export const useEditTitleStyles = createStyles(({ token, css }) => {
|
||||
return {
|
||||
editTitle: css`
|
||||
overflow: hidden;
|
||||
.busterv2-typography-edit-content {
|
||||
inset-inline-start: 0 !important;
|
||||
margin-top: 0 !important;
|
||||
margin-bottom: 0 !important;
|
||||
}
|
||||
.busterv2-input {
|
||||
padding: 0 !important;
|
||||
padding-right: 0px !important; //I changed this from 25px? to 0
|
||||
border: none !important;
|
||||
}
|
||||
`,
|
||||
editText: css``,
|
||||
editInput: css`
|
||||
padding: 0 !important;
|
||||
padding-right: 25px !important;
|
||||
border: none !important;
|
||||
`
|
||||
};
|
||||
});
|
||||
|
|
@ -1,2 +1 @@
|
|||
export * from './busterAntDStyleConfig';
|
||||
export * from './busterChartsTwMerge';
|
||||
|
|
|
|||
|
|
@ -0,0 +1,131 @@
|
|||
# API Structure Rules
|
||||
|
||||
## Directory Structure
|
||||
Each API namespace should follow this specific structure:
|
||||
|
||||
```
|
||||
src/api/{namespace}/
|
||||
├── {namespace}Requests.ts # Contains all request interfaces and types
|
||||
├── {namespace}Responses.ts # Contains all response interfaces and types
|
||||
└── index.ts # Exports all public interfaces and functions
|
||||
```
|
||||
|
||||
## File Requirements
|
||||
|
||||
### {namespace}Requests.ts
|
||||
- Must contain all request interfaces and types for the namespace
|
||||
- Each request interface should be prefixed with the namespace
|
||||
- Must include proper TypeScript types and documentation
|
||||
|
||||
```typescript
|
||||
// Example from chatRequests.ts
|
||||
import type { BusterSocketRequestBase } from '../base_interfaces';
|
||||
|
||||
/**
|
||||
* Request type for creating a new chat session or continuing an existing one.
|
||||
* @interface ChatCreateNewChat
|
||||
* @extends BusterSocketRequestBase
|
||||
*/
|
||||
export type ChatCreateNewChat = BusterSocketRequestBase<
|
||||
'/chats/post',
|
||||
{
|
||||
/** The ID of the dataset to associate with the chat. Null if no dataset is associated */
|
||||
dataset_id: string | null;
|
||||
/** The initial message or prompt to start the chat conversation */
|
||||
prompt: string;
|
||||
/** Optional ID of an existing chat for follow-up messages. Null for new chats */
|
||||
chat_id?: string | null;
|
||||
/** Optional ID of a clicked suggestion. If provided, returns that specific chat */
|
||||
suggestion_id?: string | null;
|
||||
/** Optional ID of a message to replace in an existing chat */
|
||||
message_id?: string;
|
||||
/** Optional ID of a metric to initialize the chat from */
|
||||
metric_id?: string;
|
||||
/** Optional ID of a dashboard to initialize the chat from */
|
||||
dashboard_id?: string;
|
||||
}
|
||||
>;
|
||||
```
|
||||
|
||||
This example demonstrates:
|
||||
- Proper namespace prefixing (ChatCreateNewChat)
|
||||
- Comprehensive JSDoc documentation
|
||||
- Clear type definitions with proper optional/required fields
|
||||
- Extension of a base interface (BusterSocketRequestBase)
|
||||
- Strict typing without use of `any`
|
||||
|
||||
### {namespace}Responses.ts
|
||||
- Must contain all response interfaces and types for the namespace
|
||||
- Each response interface should be prefixed with the namespace
|
||||
- Must include proper TypeScript types and documentation
|
||||
- All response callback types must be imported from `@/api/asset_interfaces` directory
|
||||
- Response types are typically found under the same namespace in the asset_interfaces directory (e.g., chat types in `asset_interfaces/chat`)
|
||||
- Must define an enum at the top of the file containing all response routes/events
|
||||
- Must export a union type at the bottom of the file that includes all response types (e.g., `export type ChatResponseTypes = | Type1 | Type2 | Type3`)
|
||||
|
||||
```typescript
|
||||
// Example of required response routes enum
|
||||
export enum ChatsResponses {
|
||||
'/chats/list:getChatsList' = '/chats/list:getChatsList',
|
||||
'/chats/unsubscribe:unsubscribe' = '/chats/unsubscribe:unsubscribe',
|
||||
'/chats/get:getChat' = '/chats/get:getChat',
|
||||
'/chats/get:getChatAsset' = '/chats/get:getChatAsset',
|
||||
'/chats/post:initializeChat' = '/chats/post:initializeChat',
|
||||
'/chats/post:generatingTitle' = '/chats/post:generatingTitle'
|
||||
}
|
||||
```
|
||||
|
||||
/**
|
||||
* Example of a properly formatted response type for chat functionality
|
||||
*/
|
||||
export type ChatList_getChatsList = {
|
||||
/** The route identifier for getting the chats list */
|
||||
route: '/chats/list:getChatsList';
|
||||
/** Callback function that receives the chat list data */
|
||||
callback: (chats: ChatListItem[]) => void;
|
||||
/** Optional error handler for when the request fails */
|
||||
onError?: (error: ApiError) => void;
|
||||
};
|
||||
|
||||
// At the bottom of the file, export a union type of all response types
|
||||
export type ChatResponseTypes =
|
||||
| ChatList_getChatsList
|
||||
| Chat_unsubscribe
|
||||
| Chat_getChat
|
||||
| Chat_getChatAsset
|
||||
| ChatPost_initializeChat
|
||||
| ChatPost_generatingTitle
|
||||
| ChatPost_generatingMessage;
|
||||
|
||||
### index.ts
|
||||
- Must export all public interfaces, types, and functions
|
||||
- Should re-export from both requests and responses files
|
||||
- Should contain any namespace-specific utility functions
|
||||
- Must use named exports (no default exports)
|
||||
|
||||
## Naming Conventions
|
||||
- All file names must use PascalCase for namespace names
|
||||
- All interface names must be prefixed with the namespace
|
||||
- All type names must be prefixed with the namespace
|
||||
- Use descriptive names that clearly indicate purpose
|
||||
|
||||
## Documentation Requirements
|
||||
- Each interface must have TSDoc comments explaining its purpose
|
||||
- Each property in interfaces must be documented
|
||||
- Include examples where appropriate
|
||||
- Document any validation requirements or constraints
|
||||
|
||||
## Type Safety
|
||||
- Avoid using `any` type. We should NEVER use any types.
|
||||
- Use strict TypeScript configurations
|
||||
- Define proper type guards when necessary
|
||||
- Use generics appropriately for reusable types
|
||||
|
||||
## Additional Guidelines
|
||||
1. Keep files focused and single-responsibility
|
||||
2. Use TypeScript's strict mode
|
||||
3. Implement proper error handling types
|
||||
4. Follow consistent formatting
|
||||
5. Include proper type exports
|
||||
6. Maintain backward compatibility
|
||||
7. Use enums for fixed sets of values
|
||||
Loading…
Reference in New Issue