Level Up Your Recreation Resource Management: A Developer's Guide to RSTBC

Are you a developer looking to contribute to the Recreation Resource Services (RSTBC) project? This guide provides a comprehensive overview of the development environment, setup process, and best practices to help you get started and contribute effectively. This guide ensures you can easily manage recreation and associated resources.

Quick Start: Setting Up Your Local Development Environment

Ready to dive in? Setting up your local environment is crucial for efficient development. Let's walk through the essentials.

• Prerequisites: Ensure you have Node.js, npm, Docker (or PostgreSQL 16), and Flyway installed. These are the foundational tools for running the application.

• Docker Compose (The Easy Way): Use Docker Compose to run the entire application with a single command. From the root directory:

  git clone [email protected]:bcgov/nr-rec-resources.git
  cd nr-rec-resources
  docker-compose up
  

  Copy

  Then, navigate to http://localhost:3000 in your browser to view the application.

• Local Installation (For More Control): Prefer a more hands-on approach? This method uses your local PostgreSQL installation.

  1. Clone the repository.
  2. Install dependencies with npm install in the base directory.
  3. Set up your database using the provided scripts.

Database Management: Flyway Migrations

Flyway, a database migration tool, keeps your database schema up-to-date.

• Install Flyway: Use Homebrew (brew install flyway) or download it directly from the Flyway website.

• Run Migrations: Configure your .env file in the /backend directory using .env.example as a template. Run these helpful commands:

  make create_db # Create the database
  make migrate   # Apply migrations
  make load_fixtures # Seed the database with initial data
  

  Copy

  To start fresh, use:

  make migrate
  

  Copy

Backend Development: NestJS Power

The backend is built with NestJS. Follow these steps to get it running.

1. Configuration: Make sure your .env file is correctly set up in the backend directory.
2. Installation: Navigate to the backend directory and run npm install.
3. Prisma Setup: Generate the Prisma client with npx prisma generate.
4. Run the Server: Start the development server using npm run dev.

Frontend Development: React & TypeScript

The frontend uses React and TypeScript.

1. Configuration: Create a .env file in the frontend directory using .env.example as a guide.
2. Installation: Navigate to the frontend directory and run npm install.
3. Run the Application: Start the frontend development server with npm run dev. Open http://localhost:3000 in your browser.

API Client Library: Staying in Sync

Keep your client library in sync with the server's API.

1. Install Java Development Kit (JDK) 17.
2. Generate the Client: Run npm run install-client-sdk from the project root. This command generates a TypeScript Axios client from your OpenAPI specification.

Prisma Schema and Client: Reflecting Database Changes

Whenever you modify the database schema, update Prisma.

1. Pull Schema: Run npx prisma db pull in the /backend directory to fetch the latest schema.
2. Generate Client: Execute npx prisma generate to update the Prisma client.
3. Location: Check the updated schema in backend/prisma/schema.prisma.

Pre-Commit Hooks: Maintaining Code Quality

Pre-commit hooks enforce code quality standards before each commit.

• Install: Run pre-commit install in the root directory.
• Automatic Checks: Pre-commit will now run linting, formatting, and secret checks on staged files.
• Skipping (Use with Caution): Use git commit -m "Your commit message" --no-verify to bypass hooks (but remember, CI will still run them!).
• Running on All Files: Use pre-commit run --all-files to apply hooks to the entire project.

Understanding API Metrics with AWS CloudWatch

This application captures key API performance and usage metrics using AWS CloudWatch Embedded Metric Format (EMF).

• How it Works: A MetricsInterceptor measures request latency, collects data (HTTP method, status code, etc.), and logs metrics to stdout in EMF format.
• Metrics Captured:
  • Latency (Milliseconds)
  • StatusCode_{statusCode} (Count)
  • ErrorCount (Count)
• Dimensions: Metrics are tagged with Operation, Method, and StatusCode for filtering in CloudWatch.
• Setting Up Metrics: For new endpoints, use the @ApiOperation decorator with an operationId to set a custom operation name.
• Viewing Metrics: Access metrics in AWS CloudWatch under the RecreationSitesAndTrailsBCAPI namespace.

Testing with Playwright

Playwright is used for end-to-end (e2e) testing. Refer to the documentation for instructions on how to run and write tests. The Page Object Model (POM) design pattern is used to create maintainable tests.

By following this guide, you can efficiently set up your development environment, understand key components, and contribute meaningfully to the Recreation Resource Services project. Let's build something amazing! By applying these tips, developers can smoothly begin their journey of managing recreation resources.