Skip to main content

Local Development

Hephaestus supports full-stack development across Java, TypeScript, and Python. This guide focuses on the development environment; production operations are covered in the Admin Guide.

Prerequisites​

Install and configure the following tools before you attempt a local build:

  1. Java JDK 21 – Required for the Spring Boot application server.
  2. Docker Desktop – Used for PostgreSQL, Keycloak, and NATS containers.
  3. Node.js LTS (>= 22.10) and npm (>= 10.8) – For the React client.
  4. Python (>= 3.13) and Poetry (>= 2.0) – For the FastAPI intelligence service.
  5. NATS CLI (optional) – Helpful when debugging webhook messages.

Open the repository using the project.code-workspace file in VS Code and install the workspace recommendations (@recommended in the Extensions view). Key extensions include:

  • Java Extension Pack
  • Spring Boot tools
  • Python and Poetry support
  • ESLint + Prettier
  • Tailwind CSS IntelliSense

JetBrains alternatives such as IntelliJ (Java), WebStorm (React), and PyCharm (Python) work equally well.

Application server​

Maven profiles and local configuration​

We ship three Maven profiles: local (default), prod, and spec. For development stick to the local profile.

Create application-server/src/main/resources/application-local.yml to override defaults:

nats:
  enabled: true
  timeframe: 1

monitoring:
  run-on-startup: true
  timeframe: 1
  sync-cooldown-in-minutes: 60
Keep it local

Never commit application-local.yml. It may contain secrets and machine-specific configuration.

Running the server​

  1. Start Docker Desktop.

  2. From server/application-server, run:

    ./mvnw spring-boot:run

  3. Access the API at http://localhost:8080 or explore http://localhost:8080/swagger-ui/index.html.

Keycloak integration​

Keycloak runs in Docker as part of the development compose stack. Configure GitHub as an identity provider before inviting external testers.

Web client (webapp)​

  1. Install dependencies:

    npm install

  2. Start Vite on port 4200:

    npm run dev

  3. Visit http://localhost:4200.

UI foundations​

  • We ship Tailwind CSS 4 in JIT mode. Keep utility classes in JSX and rely on design tokens defined in src/styles.css.
  • Ensure Tailwind IntelliSense is enabled in your IDE—typeahead prevents typos and invalid compositions.
  • Avoid premature abstractions with @apply; duplication is fine when it keeps components readable.

Component workflow (Storybook + Chromatic)​

Storybook is the source of truth for presentational components.

npm run storybook           # Local playground on http://localhost:6006
npm run build-storybook     # Static bundle for Chromatic
npm run chromatic:ci        # Visual regression in CI
  • Every new UI component ships with at least one story covering empty, loading, and error states.
  • Chromatic runs on every pull request—review visual diffs before merging.
  • Reference ui.shadcn.com for composition patterns; stick to headless Radix primitives when you need new widgets.

OpenAPI client​

The generated client in src/api is the only way the webapp talks to backend services.

npm run openapi-ts
  • Generated types drop the Dto suffix and mirror the Spring Boot API responses.
  • Pair every new endpoint with a typed TanStack Query hook for caching and invalidation.
  • Never hand-roll fetch calls—shared interceptors handle auth tokens and error telemetry.

Intelligence service (server/intelligence-service)​

  1. Create and activate a virtual environment:

    python3 -m venv .venv
    source .venv/bin/activate

  2. Install dependencies with Poetry:

    poetry install

  3. Start FastAPI:

    fastapi dev

    The service is available at http://127.0.0.1:8000 with interactive docs at /docs.

GenAI integrations​

Copy .env.example to .env and add credentials for the GenAI providers (e.g., Ollama, OpenAI) plus optional LangSmith/Langfuse instrumentation.

FastAPI fundamentals​

  • Routes live in app/routers. Keep dependencies minimal and favour dependency injection for shared services.
  • LangGraph flows sit in app/mentor. Regenerate the shared state definitions whenever you introduce new slots.
  • Auto-generated SQLAlchemy models (app/db/models_gen.py) must not be edited manually—use npm run db:generate-models:intelligence-service after schema changes.