Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/No-Country-simulation/G9-LATAM-Team-58/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything needed to get Mindloom’s API and Inference Service running on your machine, connect them to Oracle Autonomous Database, and ingest your first piece of technical content. By the end you will have a locally running system that classifies text, returns keywords and related content, and is ready for the React web interface.

​
Prerequisites

Before you start, make sure the following are installed:
ToolRequired version
Java25
Python3.12
Node.js22
DockerLatest stable
Docker ComposeV2 (bundled with Docker Desktop)
The repository ships with the Maven Wrapper (./mvnw), so a local Maven installation is not required to build or run the API.

​
Setup Steps

1
Clone the repository
2
git clone https://github.com/No-Country-simulation/G9-LATAM-Team-58.git
cd G9-LATAM-Team-58
3
Configure environment variables
4
Copy the root .env.example to .env and fill in the required values. This file supplies variables that Docker Compose interpolates into the containers — it is never committed to the repository.
5
cp .env.example .env
6
Open .env and set the five required variables:
7
# Oracle Autonomous Database — alias from tnsnames.ora inside the wallet.
# Options: techmind_high / techmind_tp / techmind_tpurgent
SPRING_DATASOURCE_URL=jdbc:oracle:thin:@techmind_tp?TNS_ADMIN=/app/wallet
SPRING_DATASOURCE_USERNAME=ADMIN
SPRING_DATASOURCE_PASSWORD=

# OCI Object Storage — the VM authenticates via Instance Principal, no keys needed.
OCI_NAMESPACE=
MODEL_BUCKET=techmind-data
8
SPRING_DATASOURCE_PASSWORD and OCI_NAMESPACE have no defaults and must be filled in before starting the containers. Leaving them blank will cause the api container to fail on startup when the db profile attempts to open a database connection.
9
Place the Oracle Autonomous Database wallet
10
Download the Instance Wallet for your Autonomous Database from the OCI Console and unzip it into a wallet/ directory at the repository root:
11
mkdir -p wallet
# Unzip your downloaded wallet archive into this directory
unzip Wallet_<your-db-name>.zip -d wallet/
12
Docker Compose mounts this directory read-only at /app/wallet inside the api container. The TNS_ADMIN environment variable already points there.
13
Start the services with Docker Compose
14
docker compose up
15
This command builds and starts two containers on the techmind bridge network:
16
  • inference — FastAPI service on internal port 8000 (not published to the host). On first start it downloads model.joblib from the OCI Object Storage bucket defined by MODEL_BUCKET. Subsequent starts reuse the cached artifact.
  • api — Spring Boot service published on host port 8080. It starts only after the Inference Service passes its health check (depends_on: condition: service_healthy), ensuring classification is available before the API accepts traffic.
    • 17
    The api container always starts with SPRING_PROFILES_ACTIVE=db, which activates the database-backed beans. Without this profile the API runs in scaffold mode: spring.autoconfigure.exclude omits DataSourceAutoConfiguration and HibernateJpaAutoConfiguration, and every endpoint that touches the database returns 503 Service Unavailable. Docker Compose sets this profile automatically — you only need to set it manually when running ./mvnw spring-boot:run outside of Docker.
    18
    Wait until you see log output confirming both services are up. You can verify the API is healthy:
    19
    curl http://localhost:8080/health
    20
    Expected response:
    21
    {
  "status": "UP",
  "timestamp": "2026-08-06T02:00:00Z",
  "dependencies": [
    { "name": "inference", "enabled": true, "reachable": true, "latencyMs": 154, "message": null },
    { "name": "database", "enabled": true, "reachable": true, "latencyMs": 308, "message": null }
  ]
}
    22
    Start the web interface
    23
    The React dev server runs outside Docker. In a new terminal:
    24
    cd web
npm install
npm run dev
    25
    The web README recommends pnpm (pnpm install && pnpm dev). Both package managers work. The dev server starts at http://localhost:5173 and points to http://localhost:8080 by default — no additional configuration needed for local development.
    26
    Ingest your first content
    27
    Send a POST /content request with a title and body. Only the body field is forwarded to the Inference Service for classification; title is stored alongside the result.
    28
    curl -X POST http://localhost:8080/content \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Intro to Spring Boot",
    "body": "Spring Boot makes it easy to create stand-alone, production-grade Spring-based applications. It takes an opinionated view of the Spring platform, which paves the way for a faster development experience."
  }'
    29
    A successful ingestion returns 201 Created with the full enriched record:
    30
    {
  "id": "usr-9f2c1e04",
  "category": "Backend",
  "probability": 0.89,
  "keywords": ["Java", "Spring Boot", "API REST"],
  "related": [
    {
      "id": "devto-2015",
      "title": "Validación con Bean Validation",
      "category": "Backend",
      "similarity": 0.76
    }
  ],
  "explanation": ["spring", "rest", "endpoint"]
}
    31
    FieldDescriptionidString identifier — corpus items keep their original ID (e.g., devto-4821); user-submitted content receives usr-{UUID}categoryOne of the 8 technical categories assigned by the classifierprobabilityClassifier confidence for the chosen category (0–1)keywordsMost relevant terms extracted from the contentrelatedUp to 5 semantically similar items already in the index, ranked by cosine similarityexplanationTerms with the highest weight in the classification decision

    ​
    What’s Next

    Your Mindloom instance is running and has indexed its first document. Here are some useful next steps:

    Architecture

    Understand how the four layers interact during ingestion and search.

    POST /content

    Full reference for the ingestion endpoint, including batch CSV upload.

    Semantic Search

    Learn how GET /search?mode=semantic queries Oracle with vector distance.

    Deployment

    Deploy Mindloom to an OCI Ampere A1 VM with the full --profile web stack.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us