Skip to content

Getting Started

Jump to bottom
Rafal Korszun edited this page May 5, 2025 · 1 revision

🚀 Getting Started with formul.ai

Welcome to formul.ai – an open-source platform for AI-powered form collection and analysis.

This guide will help you run the project locally, understand the tech stack, and learn how to join and contribute.

📦 Prerequisites

Make sure you have the following installed:

  • Node.js LTS (v18+)
  • Java 23 (for the survey service)
  • Python 3.12+
  • uv – fast Python package manager (used instead of pip)
  • Docker & Docker Compose
  • Git

🔧 Clone the Repository

git clone https://github.com/opendexcom/formul.ai
cd formul.ai

▶️ Run the Project (Using Docker)

Start everything with:

docker compose up --build

This starts:

  • Frontend served via Nginx
  • Survey service (Java 23)
  • Processing service (Python 3.12 using uv)
  • PostgreSQL database
  • Nginx reverse proxy (exposes all services on port 80)

Once running, access the app at:
👉 http://localhost

🧱 Project Structure

formul.ai/
├── frontend/            # React + @rjsf/core for the form UI
├── survey/              # Spring Boot app (Java 23) - form handling logic
├── processing/          # Python 3.12 + uv - AI analysis engine
├── gateway/             # Nginx configuration (frontend and routing)
├── docker-compose.yml   # Main Docker Compose config
└── .env                 # Local environment variables

🛠 Local Development (Without Docker)

Frontend (React)

cd frontend
npm install
npm run dev

Backend – Survey Service (Java)

cd survey
./mvnw spring-boot:run

Processing Service (Python + uv)

cd processing
uv venv .venv
source .venv/bin/activate
uv install
python app.py

This will:

  • Create a virtual environment using uv
  • Install dependencies from pyproject.toml
  • Run the Python analysis service

Make sure .venv/ is excluded from version control (already in .gitignore).

🤝 How to Join the Project

We’re building formul.ai as a community project and welcome contributors!

  1. Join our Discord to introduce yourself:
    👉 https://discord.gg/E43NyjvNUh

  2. We'll help you get onboarded based on your interests

  3. Collaborate via GitHub (Issues & Discussions)

We welcome contributions in:

  • AI/LLM pipelines (Whisper, OpenAI, Mistral, etc.)
  • Form schema design and UX
  • Docker/DevOps
  • Documentation and testing

🙌 Thanks for being here!

We’re excited to build this with the open-source community.
👉 Check out the Contributing Guide to get started.

Clone this wiki locally