as-services/DEVELOPER.md

Alerte-Secours Services - Developer Documentation

This document contains technical information for developers working on the Alerte-Secours microservices backend.

Development Quick Start

Requirements

• Docker
• Devbox
• Android SDK (for mobile development)
• Java 8+ (for Android development)

Installation

1. Clone the repository:

git clone https://codeberg.org/alerte-secours/alerte-secours
cd alerte-secours

2. Install devbox if not already installed:

curl -fsSL https://get.jetpack.io/devbox | bash

3. Enter devbox shell (this will automatically install Node.js 20 and Yarn 4.6.0):

devbox shell

4. Install dependencies:

yarn

5. Set up environment variables:

cp .env.default .env

Start Services

Start all services with Tilt:

yarn dev
# or
devbox run dev
# or run a subset of services:
tilt up api files hasura

View logs in Tilt UI (web HUD opens automatically). CLI alternative:

yarn dev:logs
# or
tilt logs

Stop services:

# If running in the foreground terminal:
Ctrl-C
# Or explicitly:
tilt down

Compose fallback (legacy):

yarn compose:up
yarn compose:down
# or via devbox:
devbox run compose:up
devbox run compose:down

Using Devbox

Once you're in the devbox shell, you have access to:

• Node.js 20 (automatically installed)
• Yarn 4.6.0 (automatically installed)
• All project scripts and environment variables
• PostgreSQL client tools

To exit the devbox shell:

exit

To run commands from outside the shell:

devbox run <command>

Available devbox scripts:

• devbox run dev - Start development environment
• devbox run dev:up - Start all services
• devbox run dev:logs - View development logs
• devbox run console - Open development console

Public Staging Environment

For development and testing, you can use our public staging environment:

• API: https://api-staging.alerte-secours.fr
• GraphQL: https://graphql-staging.alerte-secours.fr
• Web Interface: https://web-staging.alerte-secours.fr

Endpoints (Local Development)

Services

• API: http://localhost:4200
• Files: http://localhost:4292
• Hasura: http://localhost:4201
• Tasks Service
• Watchers Service
• Web: http://localhost:4203

Consoles

• Hasura Console
• Minio Console
• API Swagger
• API GraphQL
• Files API

API URLs

• /api/v1
  • /spec - API Specification
  • /oas - OpenAPI Service
  • /swagger - Swagger Documentation
  • /graphql - GraphQL Endpoint
• /status - Service Status
• / - Root Endpoint

Technical Stack

Backend

• Node.js (>=20) - Core runtime
• PostgreSQL - Primary database
• Redis - Caching and queue deduplication
• RabbitMQ - Message queue
• Hasura - GraphQL engine
• OpenAPI - API specification and documentation
• Modjo Framework - Microservices architecture

Frontend

• React - Web interface
• React Native - Mobile application
• Apollo Client - GraphQL integration
• MapView - Geolocation visualization

Infrastructure

• Docker - Containerization
• Microservices Architecture - Separate services for API, files, tasks, etc.
• CQRS Pattern - Command Query Responsibility Segregation
• Event-Driven Architecture - Using message queues

Key Features

• Real-time alerts and notifications
• Geolocation tracking and mapping
• Emergency services integration
• User authentication and authorization
• File storage and management
• Background task processing

Project Structure

services/
├── api/          # Main API service
├── app/          # Frontend application
├── files/        # File handling service
├── hasura/       # GraphQL engine
├── tasks/        # Background task processing
├── watchers/     # Event monitoring
└── web/          # Web interface

libs/
├── common/       # Shared utilities
├── postgres-types/ # Database type definitions
├── redis-queue-dedup/ # Redis queue deduplication
└── utils/        # General utilities

Contributing

We welcome contributions to Alerte-Secours. Please read our contribution guidelines before submitting pull requests.

Support

For technical support, please open an issue on our Codeberg issue tracker or GitHub issue tracker.