Developer Guide

Welcome to TimberView. This documentation is for the IT team that will install and support the application.

Monorepo containing Timberview client and server logic.

Overall

Client (/client)

  • Build: Vite

  • Framework: React

  • UI: Radix UI

  • Maps: OpenLayers

  • Data: TanStack / React Query

  • Routing: React Router

  • State: Zustand

  • E2E: Cypress

Server (/server)

  • Express & TypeScript

  • PostgreSQL + Prisma ORM

  • Multer (file uploads)

  • Puppeteer (PDF reports)

Mailer (/mailer)

Database Engine

Engine: PostgreSQL with PostGIS

Core entities:

  1. users

  2. properties

  3. assessments

  4. assessment_requests

  5. parcels

  6. manual_forms

  7. reports

  8. feedback

Other

  • User docs: /mfa-docs (Sphinx)

  • Auth: Auth0

  • Attachments: /attachments

  • Scripts: /scripts

  • Cache: Redis

Ports

Port

Service

5173

Vite dev server (HMR)

4000

Express API / production

6379

Local Redis

Local Setup

Prerequisites

  • Node.js v22

  • npm

  • PostgreSQL with PostGIS

  • Redis

  • Docker (optional)

Required env keys are in envs/.env.sample.

Install and setup

  1. Clone the repo.

  2. Set up environment variables:

    • Copy envs.json into envs/

    • Run:

    node ./scripts/create-env.mjs

    • Copy .env.local → .env

  3. Install dependencies:

    npm install

  4. Create database mfa.

  5. Run:

    npm run rebuild-envs:use

  6. Run:

    prisma migrate reset

  7. Start Redis.

  8. Adjust env settings if needed.

Start app:

npm run start

Work in Development Mode

Command:

npm run start

Notes:

  • Uses Vite dev server + Express

  • HMR enabled

  • Server runs via nodemon

Gotchas

  1. Attachments may not display on port 5173

  2. Firefox auth may be flaky

Work in Prod Mode

Command:

npm run start:prod

Serves app at:

http://localhost:4000

Running via Docker

npm run build-image
npm run run-image

Running Local Env Against Other DBs

  1. Run:

    npm run rebuild-envs

  2. Copy DB config into envs.local

  3. Start:

    npm run start

Running Tests

Unit Tests

npm run test

Cypress (E2E)

npm run start:test
npm run test:cypress

Creating a New Admin User

  1. User signs up (no profile)

  2. Get Auth0 details

  3. Run:

INSERT INTO users (id, user_type, email, first_name, last_name)
VALUES ('[ID]', 'admin', '[EMAIL]', '[FIRST NAME]', '[LAST NAME]');

Prisma ORM & Database

DB Version

  • Postgres v17.9

  • PostGIS v3.6.3

Migrations

npx prisma migrate dev --name NAME_YOUR_MIGRATION

Reset DB

npx prisma migrate reset

Database Seeding

Defined in:

/server/prisma.config.ts

Seed script:

  • Creates admin user

Render Setup

Hosting: https://render.com

Environments

  • Dev → demo.timberview.app

  • Prod → timberview.app

Database

  • Hosted PostgreSQL

Persistent Disk

  • Mounted at /attachments

Email System

Uses React Email.

Preview:

cd mailer
npm run dev

Rebuild:

cd mailer
npm run build

Deploying

Development

  • Push to main

Production

git fetch --all
git checkout production
git rebase origin/main
git push

Misc Topics

Renaming a Column

ALTER TABLE "TABLE"
RENAME COLUMN "OLD_COLUMN_NAME" TO "NEW_COLUMN_NAME";

Environment Variables

  1. Edit envs/envs.json

  2. Run:

    node ./scripts/create-env.mjs

DNS

  • Managed via Hostgator

  • Follow Render DNS docs

Auth0

  • Shared tenant across environments

Sentry

  • Used for error monitoring

Redis

  • Used for caching

Troubleshooting

  • Check Render logs

  • Run locally:

    npm run build

NPM Scripts

Script

Description

npm run start

Dev server

npm run start:prod

Production build

npm run build

Build all

npm run test

Run tests

User Documentation (mfa-docs)

Setup:

  1. Install Python & pip

  2. Create virtual environment

  3. Install:

    pip install -r mfa-docs/requirements.txt

Build:

npm run build:docs

Output:

mfa-docs/build

Last Updated: Jun 26, 2026