From d98bd177410d931281d80443093c5f0aebb6d62f Mon Sep 17 00:00:00 2001 From: Nate Kelley Date: Fri, 7 Feb 2025 20:27:07 -0700 Subject: [PATCH] naming conventions --- web/.cursor/rules/api_buster_socket_rules.mdc | 79 +++++++ web/README.md | 192 ++++++++++++++++-- .../api/buster_socket/chats/chatResponses.ts | 18 +- .../ChartLoadingComponents.tsx | 12 +- web/src/styles/busterChartsTwMerge.ts | 39 ---- web/src/styles/context/useEditTitleStyles.tsx | 25 --- web/src/styles/index.ts | 1 - web/temp.md | 131 ++++++++++++ 8 files changed, 407 insertions(+), 90 deletions(-) create mode 100644 web/.cursor/rules/api_buster_socket_rules.mdc delete mode 100644 web/src/styles/busterChartsTwMerge.ts delete mode 100644 web/src/styles/context/useEditTitleStyles.tsx create mode 100644 web/temp.md diff --git a/web/.cursor/rules/api_buster_socket_rules.mdc b/web/.cursor/rules/api_buster_socket_rules.mdc new file mode 100644 index 000000000..ddf268e55 --- /dev/null +++ b/web/.cursor/rules/api_buster_socket_rules.mdc @@ -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 \ No newline at end of file diff --git a/web/README.md b/web/README.md index 8b531d1e9..b942c2670 100644 --- a/web/README.md +++ b/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. diff --git a/web/src/api/buster_socket/chats/chatResponses.ts b/web/src/api/buster_socket/chats/chatResponses.ts index 6f20dabd7..287a0b2c1 100644 --- a/web/src/api/buster_socket/chats/chatResponses.ts +++ b/web/src/api/buster_socket/chats/chatResponses.ts @@ -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; diff --git a/web/src/components/charts/LoadingComponents/ChartLoadingComponents.tsx b/web/src/components/charts/LoadingComponents/ChartLoadingComponents.tsx index 7c5de3ba4..c6fed66be 100644 --- a/web/src/components/charts/LoadingComponents/ChartLoadingComponents.tsx +++ b/web/src/components/charts/LoadingComponents/ChartLoadingComponents.tsx @@ -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 ( -
+
{error || useShimmer === false ? ( {/* {!!error && } */} @@ -33,9 +28,8 @@ export const NoChartData: React.FC<{ className?: string; }> = ({ className = '', noDataText = 'The query ran successfully but didn’t return any data' }) => { return ( -
- +
+ {noDataText}
diff --git a/web/src/styles/busterChartsTwMerge.ts b/web/src/styles/busterChartsTwMerge.ts deleted file mode 100644 index f8364d374..000000000 --- a/web/src/styles/busterChartsTwMerge.ts +++ /dev/null @@ -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'] - } - ] - } - ] - */ - } - } -}); diff --git a/web/src/styles/context/useEditTitleStyles.tsx b/web/src/styles/context/useEditTitleStyles.tsx deleted file mode 100644 index fe9c1bcee..000000000 --- a/web/src/styles/context/useEditTitleStyles.tsx +++ /dev/null @@ -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; - ` - }; -}); diff --git a/web/src/styles/index.ts b/web/src/styles/index.ts index d4385a1a6..f363bcd52 100644 --- a/web/src/styles/index.ts +++ b/web/src/styles/index.ts @@ -1,2 +1 @@ export * from './busterAntDStyleConfig'; -export * from './busterChartsTwMerge'; diff --git a/web/temp.md b/web/temp.md new file mode 100644 index 000000000..98939deaa --- /dev/null +++ b/web/temp.md @@ -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 \ No newline at end of file