Skip to content

dev-setup.md

Latest commit

 

History

History
195 lines (129 loc) · 4.52 KB

dev-setup.md

File metadata and controls

195 lines (129 loc) · 4.52 KB
Raw

Development Setup

This document describes the software and local configuration needed to develop EdgeResQ.

Repository layout

EdgeResQ is a TypeScript monorepo with these main areas:

  • web/ — LGU triage dashboard and citizen-intake simulator (with judge controls for demoing GPS, network, battery, sensor, and dataset conditions)
  • backend/ — ingestion, verification, and event processing
  • packages/ — shared schemas, types, and utilities
  • docs/ — architecture, demo, and implementation notes
  • infra/ — Firebase, deployment, and environment assets

Required software

Install the following before working on the project:

  • Node.js
  • Bun — the backend scripts use bun run
  • Git
  • Visual Studio Code or another editor
  • Android Studio if you are developing the mobile app
  • Firebase CLI if you are working with Firebase emulators or deployment

Current package usage

The repository currently includes these runtime dependencies at the root:

  • @google/genai
  • firebase-admin
  • hono

The backend package currently defines:

  • dev: bun run --hot src/index.ts
  • start: bun run src/index.ts

The backend package also includes a package-lock.json, but the source scripts are Bun-based. Keep that in mind if you are updating dependencies or standardizing the toolchain.

Clone the repository

git clone https://github.com/ggianbrent/EdgeResQ.git
cd EdgeResQ

Install dependencies

Use the package manager that matches the project setup.

If you are working from the root

npm install

If you are working in the backend package

cd backend
npm install

If the project later standardizes on Bun, install dependencies with:

bun install

Environment setup

The backend currently expects Firebase service account credentials through the environment variable:

FIREBASE_SERVICE_ACCOUNT_JSON

This is read in backend/src/services/firebase.ts and used to initialize Firebase Admin.

Example local environment file

FIREBASE_SERVICE_ACCOUNT_JSON=...

If additional environment variables are added later, document them here and include them in an .env.example file.

Backend development

The backend includes:

  • Firebase Admin initialization
  • incident ingestion routes
  • trust score calculation
  • Google Gemini integration

Run the backend in development

From the backend/ directory:

bun run dev

Run the backend in production mode

From the backend/ directory:

bun run start

Firebase configuration

The backend uses Firebase Admin and Firestore.

If you are running locally with real Firebase access:

  1. Create or download a Firebase service account JSON file
  2. Store it securely
  3. Set FIREBASE_SERVICE_ACCOUNT_JSON
  4. Confirm the Firebase project has Firestore enabled

If the credentials are missing, the backend includes a fallback initialization path for local testing, but that will not provide full production-like behavior.

Mobile development

The mobile app is intended to support:

  • citizen reporting
  • offline queueing
  • fallback messaging
  • sensor-assisted triage

If you work on the mobile app, you will likely need:

  • Android Studio
  • Android SDK
  • emulator or physical device
  • mobile-specific app configuration once the app framework is finalized

Web dashboard development

The web app is intended to support:

  • incident mapping
  • verification state display
  • triage operations
  • incident review

If you work on the web dashboard, you will likely need:

  • Node.js
  • browser-based local development
  • frontend framework dependencies once they are defined
  • environment variables for backend/API integration

Shared packages development

Shared packages should contain reusable code such as:

  • schema definitions
  • event types
  • validation helpers
  • utility functions

Guidelines:

  • keep shared code framework-agnostic when possible
  • avoid app-specific behavior in packages
  • reuse the same types in mobile, web, and backend code

Infra and deployment

The infra/ directory is reserved for:

  • Firebase setup
  • environment configuration
  • deployment assets
  • local emulator or cloud deployment support

Suggested development flow

  1. Clone the repo
  2. Install dependencies
  3. Set environment variables
  4. Start the backend
  5. Start the web app
  6. Start the mobile app
  7. Verify end-to-end incident ingestion and triage

Notes

This document should be updated once the repository adds finalized workspace files, app manifests, and exact start commands for each surface.