Skip to main content

Part 6: Development Guide

InsightHub project began with personal innovation, but its future lies in the fusion of team wisdom. We welcome every colleague passionate about technology, efficiency, and creating value to join our developer ranks.

This section provides clear development guidelines to help you quickly set up your development environment, understand development workflows, and successfully submit your first contribution. We believe that clear standards and open communication are the foundation of pleasant collaboration.

6.1 Development Environment Setup​

6.1.1 Set Up Local Development Environment​

Before contributing code, you need to set up a development environment on your local computer that can run and modify the project. Please follow these steps:

  1. Install Node.js:

    • Node.js is the foundational environment for project backend operation and frontend building.
    • Please visit Node.js official website to download and install the latest LTS (Long Term Support) version.

  2. Install Git:

    • Git is currently the world's most popular code version control tool and the foundation tool for team collaboration.
    • Please visit Git official website to download and install the version suitable for your operating system.

  3. Install VS Code (Recommended):

    • VS Code is a free, open-source, and powerful code editor developed by Microsoft. All code in this project is written using VS Code.
    • Please visit VS Code official website to download and install.

  4. Clone Code Repository:

    • Open terminal (or Git Bash), use git clone command to clone the project's code repository to local.
    • git clone [project Git repository address]

  5. Install Project Dependencies:

    • The project is divided into frontend (/) and backend (/server) two parts. You need to install required third-party libraries for each.
    • Install frontend dependencies: 
      cd [project root directory]
      npm install
    • Install backend dependencies: 
      cd server
      npm install

  6. Configure Environment Variables:

    • Create .env file in project root directory (refer to .env.example file)
    • Configure required environment variables (see Environment Variables Configuration Guide for details)
    • Minimum Configuration (for local development testing): 
      # Google OAuth 2.0 Configuration (Required)
      VITE_GOOGLE_OAUTH_CLIENT_ID=your_client_id_here
      GOOGLE_CLIENT_SECRET=your_client_secret_here

      # Gemini API Configuration (Required)
      GEMINI_API_KEY=your_gemini_api_key_here

      # Other Configuration (Optional, for complete feature testing)
      VITE_GOOGLE_SLIDES_TEMPLATE_ID=your_template_id_here
      VITE_HELP_DOCUMENT_URL=https://your-help-doc-url.com
      AUDIT_LOG_SPREADSHEET_ID=your_audit_sheet_id_here
      APPS_SCRIPT_SLIDES_ID=your_slides_script_id_here
    • Note: .env file contains sensitive information and should not be committed to Git repository

6.1.2 First Time Running the Project​

When all dependencies are successfully installed, you can run the project locally. You need to start both the frontend development server and backend service simultaneously.

  1. Start Backend Service:

    • Open a new terminal window, enter the server directory.
    • cd server
    • npm run dev
    • When you see logs similar to 服务器启动成功 (server started successfully), it means the backend service has successfully run locally at http://localhost:8080.

  2. Start Frontend Service:

    • Open another new terminal window, stay in the project root directory.
    • npm run dev
    • When you see logs similar to VITE vX.X.X ready in XXXms, it means the frontend development server has successfully run.
    • Open the local address shown in the logs in your browser (usually http://localhost:5173), and you should see the project's login page.

Development environment has been successfully set up.

6.1.3 Git and GitHub Basics​

If you're not familiar with Git and GitHub, you can understand them as code repositories with version history.

  • Core Concepts:

    • Repository: Project code is stored in remote repositories.
    • Clone: Copy remote repository to local computer through git clone.
    • Commit: After modifying code locally, save changes through git commit with a description.
    • Push: Upload locally saved changes to remote repository through git push.
    • Pull: Synchronize latest changes pushed by other colleagues to remote repository to local through git pull.

  • Recommended Learning Resources: It's recommended to spend 1-2 hours learning Git basics, which will make team collaboration smoother.

  • Common Git Commands:

    # View current status
    git status

    # View modification content
    git diff

    # Add modifications to staging area
    git add .

    # Commit modifications
    git commit -m "Describe your changes"

    # Push to remote repository
    git push origin your-branch-name

    # Pull latest code
    git pull origin main

    # Create new branch
    git checkout -b feature/your-feature-name

6.1.4 Run Tests​

Before submitting code, it's recommended to run the project's test suite to ensure your modifications haven't broken existing functionality.

  1. Run Frontend Tests (if they exist):

    npm run test

  2. Run Code Checks:

    # Check code format
    npm run lint

    # Automatically fix format issues
    npm run lint:fix

  3. Manual Feature Testing:

    • Start frontend and backend services
    • Test core features in browser (login, file upload, analysis, etc.)
    • Check browser console for errors
    • Check backend logs for errors

6.2 Development Workflow and Standards​

To ensure project code quality, maintainability, and smooth team collaboration, we hope every contributor can jointly follow these guidelines.

6.2.1 Code Style and Comment Standards​

  • Automatic Formatting: The project has configured ESLint and Prettier for code style checking. When submitting code, they will automatically check and unify code format. Please ensure your code can pass these checks.
  • Comments Are Written for People:
    • We encourage adding clear Chinese comments for core or complex logic sections.
    • The purpose of comments is to explain "why" something is done, not "what" is done. Good code itself can explain "what" is done, while comments should be used to explain the design rationale, business logic, or issues to be aware of behind it.
    • Target Audience: Please imagine your comments are written for a smart colleague unfamiliar with this business, or even a product manager who only knows a little code. Clear comments are the best way to pass on knowledge.

6.2.2 How to Propose New Ideas (Requirements and Feature Suggestions)​

We very much welcome all kinds of new ideas that can make the project better. But to avoid unclear requirements and ineffective investment, we recommend following this process:

  1. Think First, Then Propose: When proposing a new feature idea, please don't just say "I want an XX feature." Please spend some time thinking deeply:

    • What is the core problem this feature aims to solve?
    • Who are its target users?
    • What core elements should a Minimum Viable Product (MVP) include?
    • What is the user operation workflow you envision?

  2. Documentation First: We strongly recommend writing your idea into a brief requirements document (1-Page Doc). You can use text, sketches, or even flowcharts to clearly express your vision.

  3. Public Discussion: Have your requirements document discussed publicly in the team. This helps collect feedback, discover potential issues, and ensure the idea gets everyone's approval.

  4. Collaborative Development: We encourage those who propose ideas to also become the main force in implementing them. The project founder and other core developers will be very happy to provide technical guidance and support, but we hope to create a culture where "everyone is a builder," rather than a model where "some people propose requirements and others implement them."

6.2.3 Submit Your Contribution (Code Submission Workflow)​

We adopt the industry-standard Feature Branch -> Pull Request -> Code Review collaboration workflow.

  1. Create Branch: Please don't modify code directly on the main branch. Every time you develop a new feature or fix a bug, please create a new branch from the latest main branch and give it a meaningful name (such as feature/add-new-chart or fix/login-bug).

  2. Development and Commits: Write and modify code on your own branch. After completing part of a feature, commit with git commit at any time.

  3. Create Pull Request: When your feature development is complete and passes local testing, push your branch to the remote repository and create a Pull Request (PR) on GitHub pointing to the main branch.

    • In the PR description, please clearly explain what feature you completed, what problem you solved, and what key points you want code reviewers to focus on.

  4. Code Review: At least one other core developer needs to review your code. This is a very valuable opportunity for mutual learning and ensuring code quality. Please humbly accept review comments and make corresponding modifications.

  5. Merge: When your PR is approved and passes all automated checks, it will be merged into the main branch.

Congratulations, you have successfully contributed to the project.

6.2.4 Code Commit Standards​

To maintain clarity and readability of project history, we recommend following these commit message standards:

  • Commit Message Format:

    <Type>: <Brief Description>

    <Detailed Description (Optional)>

  • Type Descriptions:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation update
    • style: Code format adjustment (doesn't affect functionality)
    • refactor: Code refactoring
    • test: Test related
    • chore: Build process or auxiliary tool changes

  • Examples:

    feat: Add market opportunity analysis feature

    Implemented market opportunity analysis feature based on Gemini AI, including:
    - Data upload and parsing
    - AI analysis invocation
    - Result visualization display

  • Notes:

    • Commit messages can be in Chinese or English
    • Brief description should clearly explain the purpose of this commit
    • If modifications involve multiple files, it's recommended to explain in detailed description

6.2.5 What to Do When Encountering Problems?​

During development, you may encounter various problems. Here are some suggestions:

  1. Consult Documentation:

    • First consult this project's documentation (especially technical implementation sections)
    • Consult official documentation for related technology stacks

  2. Search for Problems:

    • Search project Issues for similar problems
    • Search on Stack Overflow and other communities

  3. Seek Help:

    • Ask questions in team communication channels (such as Slack, email)
    • Create issues in GitHub Issues, describing problem phenomena and reproduction steps in detail

  4. Ask Questions During Code Review:

    • Code review is a good opportunity for learning and communication
    • If you have questions about review comments, please ask promptly

6.3 Troubleshooting​

6.3.1 Common Problems​

Problem 1: npm install Fails​

Possible Reasons:

  • Network issues causing dependency download failure
  • Node.js version incompatibility
  • Permission issues

Solutions:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json, reinstall
rm -rf node_modules package-lock.json
npm install

# If using proxy, configure npm proxy
npm config set proxy http://proxy.example.com:8080

Problem 2: Backend Service Startup Fails​

Possible Reasons:

  • Port is occupied
  • Environment variables not configured
  • Dependencies not installed

Solutions:

# Check port occupancy (Windows)
netstat -ano | findstr :8080

# Check port occupancy (Mac/Linux)
lsof -i :8080

# Check environment variables
cat .env

# Reinstall dependencies
cd server
rm -rf node_modules package-lock.json
npm install

Problem 3: Frontend Page Cannot Be Accessed​

Possible Reasons:

  • Backend service not started
  • Port configuration error
  • Browser cache issues

Solutions:

  • Confirm backend service is started (http://localhost:8080)
  • Clear browser cache
  • Check browser console error messages

Problem 4: OAuth Login Fails​

Possible Reasons:

  • OAuth Client ID configuration error
  • Redirect URI mismatch
  • Network issues

Solutions:

  • Check if VITE_GOOGLE_OAUTH_CLIENT_ID in .env file is correct
  • Check redirect URI configuration in Google Cloud Console
  • View error messages in browser console and network requests

6.4 Learning Resources​

6.4.1 Technology Stack Learning​

If you're not familiar with the technology stack used in the project, the following resources can help you get started quickly:

6.4.2 Project-Specific Knowledge​

Summary​

This section provides a complete development guide, including:

  1. Development Environment Setup: Set up local development environment from scratch
  2. Project Operation: How to start and test the project
  3. Git Basics: Basic concepts and operations of version control
  4. Development Standards: Code style, submission workflow, commit standards
  5. Troubleshooting: Solutions to common problems
  6. Learning Resources: Learning resources for technology stack and project-specific knowledge

We believe that by following these guidelines, you can successfully participate in project development and contribute your wisdom and strength to the project. If you have any questions or suggestions, please feel free to communicate with the team.

Related Documentation: