Developer Onboarding Guide for Digital Samba Voice Chatbot

Introduction

This document provides a comprehensive guide for developers who are new to the Digital Samba Voice Chatbot repository. It's designed to help you understand the codebase and contribute effectively, even if you're not an expert in all the technologies used.

Important Note: Setting up a local development environment is optional. All commits to the main branch are automatically deployed to https://voicebot-dev.digitalsamba.com/. This means you can make changes in three ways:

1. Directly through GitHub's web interface
2. By cloning the repository and using your preferred editor (recommended)
3. By setting up a full local development environment (for complex changes)

Repository Overview

The Digital Samba Voice Chatbot is a voice-enabled chatbot integration for Digital Samba's WebRTC video conferencing platform. The project allows users to interact with the platform using voice commands, enhancing the accessibility and user experience of Digital Samba's video conferencing solution.

Getting Started

Contribution Workflows

You have three options for contributing to this project:

Option 1: GitHub Web Interface (Quick Changes)

1. Browse the code directly on GitHub
2. Make changes using the GitHub web editor
3. Commit changes to a new branch
4. Create a pull request to merge your changes
5. View your changes at https://voicebot-dev.digitalsamba.com/ once merged to main

This approach is perfect for documentation updates, simple bug fixes, or minor enhancements.

Option 2: Clone Repository Only (Recommended)

This option lets you edit files locally with your preferred editor without setting up the full development environment:

1. Clone the repository

   git clone https://github.com/digitalsamba/voice-chatbot.git
   cd voice-chatbot
   

2. Create a new branch

   git checkout -b feature/your-feature-name
   

3. Edit files using your favorite code editor

4. Commit and push your changes

   git add .
   git commit -m "Add feature: description of your changes"
   git push origin feature/your-feature-name
   

5. Create a pull request on GitHub

6. View your changes at https://voicebot-dev.digitalsamba.com/ once merged to main

This approach gives you the benefits of local editing without needing to set up the build environment.

Option 3: Full Local Development Environment (Complex Changes)

For complex changes that require testing or extensive development, you may want to set up a complete local environment.

Setting Up Your Development Environment (Optional)

Prerequisites:

• Git
• Node.js (version X.X.X or higher)
• npm (usually comes with Node.js)
• [Any other tools needed]

Follow these steps if you choose to set up a local development environment:

1. Clone the repository

   git clone https://github.com/digitalsamba/voice-chatbot.git
   cd voice-chatbot
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   • Copy .env.example to .env
   • Fill in the required values (contact the project manager for access keys if needed)

4. Start the development server

   npm run dev
   

Project Structure

Here's an overview of the key directories and files in the project:

voice-chatbot/
├── src/                  # Source code
│   ├── api/              # API integrations
│   ├── components/       # UI components
│   ├── services/         # Service layer
│   │   ├── speech/       # Speech recognition services
│   │   ├── nlp/          # Natural language processing
│   │   └── samba/        # Digital Samba integration
│   ├── utils/            # Utility functions
│   └── main.js           # Application entry point
├── config/               # Configuration files
├── public/               # Static assets
├── tests/                # Test suite
└── docs/                 # Documentation

Key Concepts

Voice Recognition

The voice recognition system uses [technology name] to convert spoken language into text. This happens in src/services/speech/recognition.js.

Natural Language Processing

Once the speech is converted to text, the NLP system interprets the user's intent. This is handled in src/services/nlp/.

Digital Samba Integration

The integration with Digital Samba's platform is managed through their SDK. The key integration points are:

• Room joining and session management
• Audio/video stream handling
• User presence and status

Development Workflow

Making Changes

Option 1: Via GitHub Web Interface

1. Navigate to the repository on GitHub
2. Browse to the file you want to edit
3. Click the pencil icon to edit the file
4. Make your changes in the editor
5. Scroll down and add a descriptive commit message
6. Select "Create a new branch for this commit and start a pull request"
7. Name your branch appropriately (e.g., feature/add-voice-command)
8. Click "Propose changes"
9. Complete the pull request form and submit

Option 2: Via Local Editor (Without Full Environment)

1. Make your changes in your preferred editor
2. Commit your changes with a descriptive message:

   git add .
   git commit -m "Add feature: description of your changes"
   

3. Push your branch to the repository:

   git push origin feature/your-feature-name
   

4. Create a pull request on GitHub for review

Option 3: Via Full Local Development

1. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   

2. Make your changes, following the coding standards outlined below.

3. Test your changes locally:

   npm test
   

4. Commit your changes with a descriptive message:

   git commit -m "Add feature: description of your changes"
   

5. Push your branch to the repository:

   git push origin feature/your-feature-name
   

6. Create a pull request on GitHub for review.

Deployment

The project has an automated CI/CD pipeline set up. Any code merged into the main branch will automatically be deployed to the development environment at:

https://voicebot-dev.digitalsamba.com/

Important Notes about Deployment:

• Deployment happens automatically - no manual steps required
• Changes typically appear within 5-10 minutes after merging to main
• You can view the deployment status in the GitHub Actions tab
• Always check your changes on the dev site after deployment
• Deployment failures will be notified via GitHub

Before merging to main, ensure:

• All tests pass (if running locally)
• Your code has been reviewed and approved
• Your changes meet the project's quality standards

Testing

Option 1: Testing Without Local Setup

If you're not using a local development environment, you can still validate your changes:

1. Create a pull request - this will trigger automated tests in GitHub Actions
2. Review the test results in the pull request status
3. Request a code review from team members
4. Test directly on the dev environment after merging to main
5. Check your changes in action on https://voicebot-dev.digitalsamba.com/

Option 2: Testing With Git Clone Only

If you've cloned the repository but haven't set up the full environment:

1. Review your code changes carefully in your editor
2. Use your editor's linting tools if available
3. Create a pull request to trigger automated tests
4. After merging, test on the dev environment

Option 3: Testing Locally

If you've set up a local development environment, you can run tests locally:

npm test

For component testing, use:

npm run test:components

Common Tasks

Adding a New Voice Command

Via GitHub Web Interface:

1. Navigate to src/services/nlp/intents.js on GitHub
2. Add your new intent definition
3. Create a new handler file in the src/services/nlp/handlers/ directory
4. Update documentation as needed
5. Create a pull request with your changes

Via Local Editor (Without Full Environment):

1. Open src/services/nlp/intents.js in your editor
2. Add your new intent definition
3. Create a handler file in src/services/nlp/handlers/
4. Update documentation as needed
5. Commit and push your changes
6. Create a pull request

Via Full Local Development:

1. Define the intent in src/services/nlp/intents.js
2. Create a handler for the intent in src/services/nlp/handlers/
3. Add test cases in tests/nlp/
4. Update the documentation in docs/commands.md
5. Test locally and submit a pull request

Modifying the UI

Via GitHub Web Interface:

1. Navigate to the component you want to modify in src/components/
2. Make your changes following the project's design guidelines
3. Create a pull request with your changes
4. After merging, check the deployment to verify your changes

Via Local Editor (Without Full Environment):

1. Open the component file in src/components/ using your editor
2. Make your changes following the project's design guidelines
3. Commit and push your changes
4. Create a pull request
5. After merging, check your changes on the deployment site

Via Full Local Development:

1. Locate the relevant component in src/components/
2. Make your changes following the project's design guidelines
3. Test the changes in different browsers and screen sizes
4. Update any affected documentation
5. Submit a pull request with your changes

Troubleshooting

Common Issues

1. Speech recognition not working

   • Check browser permissions for microphone access
   • Verify WebRTC compatibility with your browser

2. Integration with Digital Samba failing

   • Ensure your API keys are correctly set in .env
   • Check the console for specific error messages

3. Build errors

   • Run npm clean-install to refresh dependencies
   • Check for Node.js version compatibility

Getting Help

If you're stuck or have questions:

1. Check existing documentation in the docs/ directory
2. Look for similar issues in the project's issue tracker
3. Contact [team contact info] for direct assistance

Coding Standards

• Use ES6+ features where appropriate
• Follow the existing code formatting style (enforced by ESLint)
• Write meaningful comments for complex logic
• Include JSDoc comments for functions
• Create unit tests for new functionality

Resources

• Digital Samba SDK Documentation
• WebRTC Documentation
• Speech Recognition API
• Project Wiki

This guide is a living document. If you find areas that need improvement or have suggestions, please update it or create an issue with your recommendations.