Encovia Backend

A Node.js + TypeScript REST API built with Express and PostgreSQL.

Requirements

• Node.js 18+
• npm or yarn or pnpm
• PostgreSQL (if using the database locally)

Setup

1. Install dependencies:

npm install

2. Create environment file:

cp .env.example .env

Edit .env with your values. Common variables:

PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/encovia

Scripts

• npm run dev — Start the server in watch mode with tsx.
• npm run build — Compile TypeScript to dist/.
• npm start — Run the compiled server from dist/.

Development

• Source code lives in src/ (entry: src/index.ts).
• Built files output to dist/ (entry: dist/index.js).

Run in watch mode during development:

npm run dev

API

Base URL: http://localhost:${PORT} (default 4000 if not set)

• Health

  • Method: GET
  • Path: /health
  • Response: { ok: true }

• Create Place

  • Method: POST
  • Path: /places
  • Request body JSON:
    • name string (required)
    • description string (optional)
    • category string (required)
    • latitude number (required)
    • longitude number (required)
    • address string (optional)
    • additionalInfo string (optional)
  • Success 201 response:
    • { id: string }
  • Error 400: { error: 'Invalid payload' }

  Example:

  curl -X POST http://localhost:4000/places \
    -H 'Content-Type: application/json' \
    -d '{
      "name":"Community Garden",
      "description":"Shaded benches",
      "category":"park",
      "latitude":5.6037,
      "longitude":-0.1870,
      "address":"12 Palm St",
      "additionalInfo":"water tap nearby"
    }'

• List Places

  • Method: GET
  • Path: /places
  • Success 200 response (array of places):
    • id string
    • name string
    • description string
    • category string
    • location object
      • latitude number
      • longitude number
    • address string
    • additionalInfo string
    • isUserContributed boolean
    • createdAt string (ISO timestamp)

  Example:

  curl http://localhost:4000/places

• Nearby Places

  • Method: GET
  • Path: /places/nearby
  • Query:
    • lat number (required)
    • lon number (required)
    • radius_km number (optional, default 10)
  • Response: same shape as List Places (array filtered by Haversine distance)

  Example:

  curl 'http://localhost:4000/places/nearby?lat=5.6037&lon=-0.1870&radius_km=5'

• Daily Content (Fact + Action)

  • Method: GET
  • Path: /daily
  • Query:
    • day integer 1–180 (optional). If omitted or out of range, uses today mapped into 1–180.
  • Success 200 response:
    • dayIndex integer
    • fact string
    • action string

  Example:

  curl http://localhost:4000/daily
  curl 'http://localhost:4000/daily?day=42'

• Daily Fact only

  • Method: GET
  • Path: /daily/fact
  • Query: day integer 1–180 (optional)
  • Success 200 response:
    • dayIndex integer
    • fact string

  Example:

  curl http://localhost:4000/daily/fact
  curl 'http://localhost:4000/daily/fact?day=42'

• Daily Action only

  • Method: GET
  • Path: /daily/action
  • Query: day integer 1–180 (optional)
  • Success 200 response:
    • dayIndex integer
    • action string

  Example:

  curl http://localhost:4000/daily/action
  curl 'http://localhost:4000/daily/action?day=42'

Seeding Daily Content

Tables daily_facts and daily_actions are created on startup if missing. To seed 180 rotating entries:

psql "$DATABASE_URL" -f scripts/seed_daily_content.sql

Production

Build and start:

npm run build
npm start

Environment & Secrets

This project uses dotenv. Do not commit real secrets. Keep only example keys in .env.example.

License

Proprietary