Location: src/app
Description: The primary framework for building the user interface. It manages routing, server-side rendering, and client-side interactivity. The (auth) and (dashboard) groups in the app directory define distinct sections of the application, handling public authentication flows and protected simulation dashboards, respectively.
Key Files:
- src/app/layout.tsx: Root layout for the application.
- src/app/page.tsx: Landing page.
- src/app/(auth)/sign-in/page.tsx, src/app/(auth)/sign-up/page.tsx: Authentication pages.
- src/app/(dashboard)/dashboard/page.tsx: Main dashboard.
- src/app/(dashboard)/simulation/page.tsx: The core simulation interface.
Location: src/components, src/app/_components
Description: A collection of reusable UI components ranging from generic design system elements to specific application features.
- UI Library (src/components/ui): Provides a consistent and accessible design system using Radix UI primitives and styled with Tailwind CSS (e.g., button.tsx, input.tsx, dialog.tsx).
- Authentication Components (src/components/(auth)): Handles the visual aspects of user login and registration (sign-in.tsx, sign-up.tsx).
- Chat Components (src/components/(chat)): Forms the interactive chat interface for the simulation. This includes ChatPage.tsx, ChatWindow.tsx for displaying messages, ElevenLabsRecorder.tsx for capturing voice input, and MessageBubble.tsx for rendering individual messages.
- Dashboard Components (src/components/dashboard): Specific UI elements for the dashboard, like SkillCard.tsx.
- App-Specific Components (src/app/_components): Components integral to the overall user flow, such as landing-page.tsx, level-selection.tsx, and require-personality.tsx, which guides users through initial setup and choices.
- Collaboration: These components are assembled by Next.js pages and interact with the tRPC API for data fetching and mutations, and with better-auth for authentication state.
Location: src/server/api, src/trpc
Description: Provides an end-to-end type-safe API, eliminating the need for runtime API validation. It ensures that the data structures exchanged between the frontend and backend are always in sync.
Key Files:
- src/server/api/trpc.ts: Initializes the tRPC server, defines the request context (which includes database access and user session information), and establishes publicProcedure and protectedProcedure for secure API endpoint creation.
- src/server/api/root.ts: The main router that combines all individual domain-specific routers into a single, cohesive API.
- src/server/api/routers/: Contains modular routers for different parts of the application:
- elevenlabs.ts: Endpoints for ElevenLabs integration (e.g., generating signed URLs for voice conversations).
- evaluation.ts: API for skill evaluation data.
- notes.ts: API for managing simulation notes.
- post.ts: Example router (from T3 Stack boilerplate).
- user.ts: User-related API endpoints (e.g., fetching user profile, updating personality).
- video.ts: API for retrieving video URLs from Vercel Blob.
- voice.ts: General voice-related API endpoints.
- src/trpc/react.tsx: The client-side setup for tRPC, providing React hooks (api.useQuery, api.useMutation) that enable type-safe data fetching and mutations in frontend components, integrated with @tanstack/react-query for robust data management.
- Collaboration: Frontend components use api hooks to interact with these procedures, which in turn use drizzle-orm to communicate with the database and other services like ElevenLabs.
- Location: drizzle.config.ts, drizzle/, src/server/db
- Description: A TypeScript ORM used to define the database schema and interact with the PostgreSQL database. It allows for type-safe database queries and migrations.
- drizzle.config.ts: Configuration for Drizzle Kit, specifying the schema file, database dialect, credentials, and table filter.
- drizzle/: Contains Drizzle migration files (e.g., 0000_violet_supreme_intelligence.sql, meta/).
- src/server/db/schema.ts: Defines the structure of all database tables (e.g., user, session, account, verification, posts, simulationNotes), including columns, data types, and relationships. The simulationNotes table is crucial for storing student performance data.
- src/server/db/index.ts: Initializes the Drizzle ORM client, connecting to the PostgreSQL database using postgres.js and exposing the db instance for use in tRPC procedures.
- Collaboration: The db instance is injected into the tRPC context, allowing API procedures to perform database operations. better-auth also uses Drizzle via its adapter.
- Location: src/lib/auth.ts, src/lib/auth-client.ts, src/app/(auth)/api/auth/[...all]/route.ts, src/lib/protected-page.tsx
- Description: Manages user authentication, including registration, login, and session handling.
- src/lib/auth.ts: Server-side better-auth configuration, specifying the Drizzle adapter for database integration and base URLs for authentication callbacks.
- src/lib/auth-client.ts: Client-side utilities for authentication, providing signIn, signUp, signOut, and useSession hooks for React components.
- src/app/(auth)/api/auth/[...all]/route.ts: Next.js API route that handles all authentication-related requests, serving as the backend for better-auth.
- src/lib/protected-page.tsx: A React Server Component that acts as a guard, ensuring that only authenticated users can access specific routes within the application. It redirects unauthenticated users to the sign-in page.
- Collaboration: Integrates with Drizzle for storing user data and sessions, and with Next.js for route protection and API handling.
Location: src/components/(chat)/, src/server/api/routers/elevenlabs.ts, src/utils/voice-utils.ts, src/utils/convertWebmToMp3.ts
Description: Provides realistic voice-based interactions for the simulation, allowing students to speak to and hear responses from the AI pet owner.
- @elevenlabs/react: Used in frontend components for managing ElevenLabs interactions.
- ElevenLabsRecorder.tsx: Manages recording audio input from the user (student).
- ElevenLabsConversation.tsx: Orchestrates the voice conversation flow, including playing AI-generated speech.
- src/server/api/routers/elevenlabs.ts: Defines server-side tRPC procedures for secure interaction with the ElevenLabs API, potentially for generating temporary credentials or signed URLs for WebRTC voice communication.
- src/utils/voice-utils.ts: Provides VOICE_IDS and helper functions to select specific ElevenLabs voices based on gender.
- src/utils/convertWebmToMp3.ts: Converts recorded WebM audio to MP3 format, ensuring compatibility with ElevenLabs APIs.
- Collaboration: Works closely with OpenAI (likely for text-based AI responses that are then vocalized) and the chat components to create an immersive voice simulation.
Location: src/lib/blob.ts, src/server/api/routers/video.ts
Description: A cloud-based object storage solution for storing and serving large files, particularly video assets used in the simulation scenarios.
- src/lib/blob.ts: Contains utility functions (getVideoUrl, getVideoUrls) to retrieve public URLs for video files stored in Vercel Blob, based on their filenames. These functions handle token management and robust error handling.
- src/server/api/routers/video.ts: A tRPC router providing API endpoints to fetch these video URLs to the frontend.
- Collaboration: Video components in the frontend fetch URLs from these tRPC endpoints to display case-specific videos.
Location: src/lib/utils.ts, src/utils/
Description: A collection of helper functions that support various aspects of the application.
- src/lib/utils.ts: Includes cn for concatenating Tailwind CSS classes and base64ToBlobURL for converting base64 strings to Blob URLs.
- src/utils/createPrompt.ts: A critical module for dynamically generating comprehensive AI prompts for the ElevenLabs integration. These prompts are highly customizable based on the specific communication skill being practiced, case details, pet owner persona, and strict instructions for the AI's behavior, ensuring a tailored and effective learning experience for students.
- src/utils/convertWebmToMp3.ts: As detailed in the ElevenLabs section, handles audio format conversion.
- Collaboration: These utilities are used across the frontend and backend to streamline development and provide core functionalities.
Let's consider a scenario where a veterinary student (user) logs in and starts a simulation with voice interaction:
- Login: The student navigates to /sign-in. The sign-in.tsx component (React) uses authClient.signIn (src/lib/auth-client.ts) to send credentials to the Next.js API route for authentication (src/app/(auth)/api/auth/[...all]/route.ts). The server-side betterAuth (src/lib/auth.ts) authenticates against the Drizzle database (src/server/db).
- Dashboard Access: After successful login, the user is redirected to /dashboard. The protected-page.tsx (src/lib) ensures the user is authenticated before rendering the dashboard content.
- Case Selection: On the dashboard, the student selects a veterinary case and a communication skill to practice (e.g., "History Taking"). This action might trigger a tRPC query (via src/trpc/react.tsx) to the evaluationRouter or userRouter (src/server/api/routers) to fetch case details or update user progress in the Drizzle database.
- Simulation Start: The student enters the simulation. The simulation/page.tsx loads the ChatPage.tsx and ChatWindow.tsx components.
- AI Prompt Generation: The createPrompt.ts utility is used to dynamically generate a detailed prompt for the AI pet owner. This prompt includes the pet owner's persona, the presenting complaint, the specific communication skill being practiced, and strict instructions for the AI's behavior.
- Voice Input (Student): The student speaks into their microphone. The ElevenLabsRecorder.tsx component captures their voice as a WebM audio blob.
- Audio Conversion: The webmToMp3 function (src/utils/convertWebmToMp3.ts) converts the WebM audio to MP3 format.
- ElevenLabs Interaction (Speech-to-Text & Text-to-Speech):
- Live stream with voice starts the ElevenLabs API (possibly via a tRPC endpoint in src/server/api/routers/elevenlabs.ts).
- ElevenLabs processes the student's speech (speech-to-text) and then, based on the generated AI prompt, provides a textual response from the AI pet owner (likely involving an OpenAI interaction on the backend, orchestrated by a tRPC procedure).
- ElevenLabs then synthesizes this textual response into speech (text-to-speech) using a selected voice (getVoiceIdByGender from src/utils/voice-utils.ts).
- Voice Output (AI Pet Owner): The synthesized AI voice is played back to the student through the ElevenLabsConversation.tsx component and displayed as a message in the ChatWindow.tsx.
- Notes: Throughout the simulation, the student might take notes, which are saved via a tRPC mutation to the notesRouter and stored in the simulationNotes table in the Drizzle database.
- Evaluation: At the end of the simulation, the interaction can be evaluated by calling to OpenAI API.
- Video Integration (Optional): If a case involves a video, the frontend would request the video URL from the videoRouter (tRPC), which uses getVideoUrl (src/lib/blob.ts) to fetch the URL from Vercel Blob storage.