Guide for New Developers

WIP!! Everything below was generated by a custom chatgpt Ariel created: https://chatgpt.com/g/g-bMEXH2CLV-home-unite-us-pro

Home Unite Us Codebase Documentation for New Developers

---

Table of Contents

1. Introduction
2. Project Structure
3. Setting Up Your Development Environment
4. Understanding the Codebase
5. Key Technologies and Dependencies
6. Working with Git and GitHub
7. Best Practices for Contributing
8. Common Commands
9. FAQ

---

1. Introduction

Welcome to the Home Unite Us codebase! This guide will help you navigate the codebase, understand the key parts, and set up your environment for contributing to the project.

If you have any questions or need help, please feel free to reach out via the #home-unite-us-dev Slack channel.

---

2. Project Structure

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

HomeUniteUs/
│
├── /app/             # Frontend code (React)
├── /api/             # Backend code (Python/Flask, started converting to FastAPI Sept 2024)
├── /scripts/         # Utility scripts for deployment or development
├── README.md         # Project overview and setup instructions
└── docker-compose.yml # Docker configuration for local development

• /app/: Contains the frontend code, built with React.
• /api/: Houses the backend code, a REST API built using Python and Flask, with Connexion for API routing.
• /scripts/: Utility scripts for various tasks such as deployment and automation.
• /docker-compose.yml: Manages multi-container Docker applications for local development.

---

3. Setting Up Your Development Environment

To get started with the project, follow these steps:

1. Clone the repository:

   git clone https://github.com/hackforla/HomeUniteUs.git

2. Install dependencies: Navigate to both the /app and /api directories and run the following command in each:

   npm install   # For the frontend (app)
   pip install -r requirements.txt  # For the backend (api)

3. Set up environment variables: Copy the .env.example file in both the /app and /api directories to a .env file and update any necessary credentials or settings by contacting a team member for the required values.

4. Start the development servers:

   • Using Docker (recommended):

     docker-compose up

     The frontend should be available at http://localhost:4040 and the backend API at http://localhost:8080.

5. Access the app:

   • Frontend: Runs on http://localhost:4040
   • Backend: API runs on http://localhost:8080

---

4. Understanding the Codebase

Frontend (React)

• The frontend is built with React and communicates with the backend API for data.
• Main entry point: /app/src/index.tsx
• Components are organized in /app/src/components/.
• We use Redux for state management and Material UI for styling and UI components.

Backend (Python/Flask)

• The backend is a REST API built using Flask and connexion for routing and validation.
• Main entry point: /api/app.py
• Routes and OpenAPI specifications are defined in /api/routes/ and /api/spec/.
• We use SQLAlchemy as the Object-Relational Mapper (ORM) to interact with a PostgreSQL database.

---

5. Key Technologies and Dependencies

• React: Used for building the frontend user interface.
• Node.js & Vite: For running the frontend dev server and building production-ready files.
• Python & Flask: Backend server and API framework.
• PostgreSQL & SQLAlchemy: For database operations.
• Vitest & Cypress: Used for testing (unit tests and end-to-end tests).
• Docker: To containerize the app and manage development environments.

Make sure to check the package.json (in /app) and requirements.txt (in /api) for the full list of dependencies.

---

6. Working with Git and GitHub

1. Branching Strategy:

   • Main branches:
     • main: The production-ready code.
     • development: The active development branch.
   • Feature branches:
     • When working on new features or bug fixes, create a new branch off development:

       git checkout -b feature/your-feature-name

2. Pull Requests:

   • Make sure to open a pull request from your feature branch into the development branch once your work is complete.
   • Include a detailed description of the work, and reference any issues it resolves.

3. Commit Messages:

   • Use descriptive commit messages, following this pattern:

     feat: Add new feature for user authentication
     fix: Correct typo in homepage banner
     

---

7. Best Practices for Contributing

• Code Consistency: Follow the existing code style. We use ESLint for the frontend and Flake8 for the backend. Run the following before pushing:

  npm run lint   # Frontend
  flake8 .       # Backend

• Testing: Make sure your code is tested. Add tests for any new functionality, and ensure all existing tests pass:

  • Unit tests:

    cd app
    npm test   # Frontend (using Vitest)

  • End-to-end tests:

    cd app
    npm run cypress:open  # Launch Cypress for e2e tests

• Pull Requests: Keep PRs small and focused. If your PR is too large, consider splitting it into multiple smaller ones.

• Documentation: Update relevant documentation if you make changes to the code.

---

8. Common Commands

Here are some common commands you will use during development:

• Start frontend development server:

  cd app
  npm run dev

• Start backend development server:

  cd api
  flask run

• Run tests:

  cd app
  npm test   # Frontend unit tests
  npm run cypress:open   # Frontend e2e tests
  
  cd api
  pytest   # Backend tests

• Lint code:

  cd app
  npm run lint   # Frontend
  
  cd api
  flake8 .   # Backend

• Format code:

  cd app
  npm run format   # Frontend

---

9. FAQ

How do I report bugs or request features?

You can report bugs or request features by opening an issue on our GitHub Issues page.

How do I get help with something?

Feel free to reach out to the team via GitHub discussions or our Slack channel. We're here to help!

---