Logo

3.3. Project Structure

The codebase is organized into distinct directories:

  • .: Contains root configuration files:
    • package.json: Project metadata, dependencies, scripts.
    • vite.config.ts: Vite build/dev server configuration.
    • tsconfig.json, tsconfig.app.json, tsconfig.node.json: TypeScript configuration for the project, frontend app, and Node-specific parts (like vite.config.ts).
    • tailwind.config.js, postcss.config.js: Tailwind CSS configuration.
    • .eslintrc.cjs: ESLint configuration for code linting.
    • .prettierrc: Prettier configuration for code formatting.
    • .gitignore: Specifies intentionally untracked files for Git.
    • components.json: shadcn/ui configuration.
    • index.html: Main HTML entry point for the Vite app.
    • README.md: Project overview and setup instructions.
    • LICENSE: Project license (MIT).
  • .cursor/: Contains configuration files for the Cursor AI code editor.
    • rules/: Contains specific guidelines for writing code within this project (e.g., convex_rules.mdc, project.mdc). These enforce consistency, especially regarding Convex and shadcn/ui usage.
  • convex/: Houses all backend code executed by Convex.
    • _generated/: (Auto-generated) Contains TypeScript types (api.d.ts, dataModel.d.ts) and JavaScript helpers (api.js, server.js) generated by Convex based on your schema and function definitions. Do not edit directly.
    • agents/: Logic related to AI agents.
      • schema.ts: Defines the Convex schema structure for the agents table.
      • model.ts: Core functions for creating, reading, updating, deleting (CRUD) agents, including helpers like createAgentAvatarUrl, listMine, getMine.
      • queries.ts: Public Convex query functions exposed to the frontend (e.g., listMine, getMine, findMention).
      • mutations.ts: Public Convex mutation functions (e.g., create, updateMine, removeMine, shuffleAvatar).
      • internalQueries.ts, internalMutations.ts: Convex functions intended only for use by other backend functions (not directly callable from the client).
    • ai/: Contains the core logic for AI interactions.
      • agentReplyToMessage.ts: Action handling messages directed at a specific agent.
      • triageMessage.ts: Action handling messages without mentions, routing them via the Triage agent.
      • history.ts: Functions for retrieving message history for AI context.
      • instructions.ts: Functions to construct the system prompts/instructions for different AI tasks (triage, reply).
      • messages.ts: Logic for preparing message lists in the format required by the AI model.
      • tools.ts: Implementation of the tools available to the AI agents (using exa-js, resend, and calling other Convex functions). Defines createToolsForAgent.
      • utils.ts: Helper functions for common AI-related tasks (e.g., sending system messages, managing agent status, error handling).
    • conversationMessages/: Logic for managing messages within conversations. Structured similarly to agents/ with schema.ts, model.ts, queries.ts, mutations.ts, internalQueries.ts, internalMutations.ts, internalActions.ts (processMessage action is key).
    • conversationParticipants/: Logic for managing the relationship between users/agents and conversations. Similar structure (schema.ts, model.ts, etc.).
    • conversations/: Logic for managing conversation threads. Similar structure.
    • users/: Logic related to user data.
      • model.ts: Core user data access functions (find, get, getMyId, getMe).
      • queries.ts: Public queries (getMe, findMention).
    • auth.config.ts: Configuration for the @convex-dev/auth library (providers, password validation).
    • auth.ts: Server-side setup for @convex-dev/auth, exporting auth, signIn, signOut, etc.
    • http.ts: Defines Convex HTTP endpoints, primarily used by @convex-dev/auth for handling OAuth callbacks and password auth routes.
    • schema.ts: The main database schema definition for the entire Convex application. It imports schemas from subdirectories and includes authTables.
    • tsconfig.json: TypeScript configuration specific to the Convex backend environment.
  • public/: Static assets served directly by the web server (e.g., convex.svg, logo.svg).
  • shared/: TypeScript code designed to be used by both the frontend (src/) and the backend (convex/).
    • ensure.ts: Utility functions for asserting non-null/undefined values.
    • filter.ts: Utility functions for filtering arrays (e.g., isNotNullOrUndefined).
    • mentions.ts: Core logic for parsing (parseMentionsFromMessageContent, splitMessageContent) and creating (createMentionString) the mention syntax used in messages.
    • mentions.test.ts: Vitest unit tests for the mention logic.
    • misc.ts: Miscellaneous utility functions (pick, exhaustiveCheck, wait) and shared types (MessageReference, AgentTool).
    • predefinedAgents.ts: An array of default agent configurations used when creating new agents.
    • tools.ts: Definitions of available agent tools (toolDefinitions), including names, descriptions, and Zod parameter schemas. Also defines userChoosableToolDefinitions and alwaysIncludedTools.
  • src/: Contains all frontend code (React application).
    • components/: Reusable React UI components.
      • authenticated/: Components visible only when the user is logged in. Contains subdirectories for major features like agents, chat, conversations, sidebar.
      • unauthenticated/: Components for the sign-in/sign-up experience.
      • misc/: Miscellaneous components and hooks (e.g., error handling errors.ts, custom hooks hooks.ts).
      • ui/: shadcn/ui components. These are typically added via the shadcn CLI and provide the core UI building blocks (Button, Card, Dialog, Avatar, etc.).
    • lib/: Frontend-specific utility functions.
      • utils.ts: Contains cn function for merging Tailwind classes (from shadcn/ui setup).
    • App.tsx: The root React component, setting up providers (RouteProvider, ConvexAuthProvider, ConvexQueryCacheProvider) and rendering authenticated/unauthenticated content.
    • main.tsx: The application entry point, responsible for initializing the Convex client, auth provider, and rendering the root component (App.tsx).
    • index.css: Main CSS file, includes Tailwind directives and base styles/theme variables.
    • routes.ts: Defines application routes using type-route, providing type-safe routing and navigation helpers (useRoute, routes, useCurrentConversationId, etc.).
    • vite-env.d.ts: TypeScript definitions for Vite environment variables.

3.4. Key Technologies & Libraries

  • Frontend:
    • React 19: Core UI library.
    • Vite: Fast frontend build tool and development server.
    • TypeScript: Static typing for JavaScript.
    • Tailwind CSS: Utility-first CSS framework for styling (tailwind.config.js, index.css).
    • shadcn/ui: Collection of accessible and customizable UI components built on Radix UI and Tailwind CSS (src/components/ui/, components.json).
    • type-route: Type-safe routing library (src/routes.ts).
    • convex/react: Official Convex hooks (useQuery, useMutation) for interacting with the backend and managing real-time data subscriptions.
    • @convex-dev/auth/react: Hooks (useConvexAuth, useAuthActions) for frontend authentication state and actions.
    • convex-helpers/react/cache: Provides ConvexQueryCacheProvider for potential query caching/optimizations.
    • react-mentions: Component used in ChatInput.tsx to handle the @ mention input experience.
    • react-markdown / remark-gfm: Used in ParticipantMessage.tsx to render Markdown content from messages.
    • lucide-react: Icon library used throughout the UI.
    • sonner: Toast notification library (src/App.tsx).
    • date-fns: Utility library for date formatting/manipulation (used in useTimeAgo hook).
    • clsx / tailwind-merge: Utilities for constructing CSS class names (src/lib/utils.ts).
  • Backend (Convex):
    • Convex TypeScript SDK: Provides functions (query, mutation, action, internalQuery, etc.) to define backend logic (convex/_generated/server.js, convex/_generated/server.d.ts).
    • Convex Database: Integrated real-time, transactional NoSQL database. Schema defined in convex/schema.ts.
    • @convex-dev/auth/server: Server-side library for handling authentication logic (convex/auth.ts).
    • Convex Actions: Environment for running arbitrary Node.js code, interacting with third-party APIs, and orchestrating queries/mutations. Files often marked with "use node";.
  • AI & Integrations:
    • ai / @ai-sdk/openai: Vercel AI SDK used within Convex actions for streamlined interaction with OpenAI models, including tool usage (convex/ai/agentReplyToMessage.ts, convex/ai/triageMessage.ts, convex/ai/tools.ts).
    • OpenAI API: Used via the AI SDK for generating text responses and deciding on tool calls.
    • exa-js: Official JavaScript client for the Exa API, used in the webSearch tool (convex/ai/tools.ts).
    • resend: Official JavaScript client for the Resend API, used in the sendEmail tool (convex/ai/tools.ts).
  • Shared:
    • TypeScript: Used for defining shared types and logic.
    • zod: Used in shared/tools.ts to define the expected parameters for each agent tool, providing runtime validation and type safety for AI tool calls.
    • convex-helpers: Utility functions for working with Convex (e.g., pick used in shared/misc.ts and convex/ai/tools.ts).

3.5. Running Tests

The project uses Vitest for unit testing, primarily focused on the shared mention logic currently.

  • To run tests: 
    bun test
  • Test files are located alongside the code they test (e.g., shared/mentions.test.ts).

3.6. Linting & Formatting

  • Linting: ESLint is configured (.eslintrc.cjs) to enforce code quality and catch potential errors. TypeScript type checking is also part of the lint process. 
    bun lint
  • Formatting: Prettier (.prettierrc) is used for automatic code formatting. It’s recommended to set up your editor to format on save using Prettier. You can also run it manually: 
    bunx prettier --write . # Format all supported files
Loading...