dumanoj/boox repository overview

⁠Boox - AI Chat Application

A modern chat application built with React and Spring Boot that uses Ollama for local AI models.

⁠⚡ Zero-Setup Quick Start

Just Docker required — no repo clone, no build, no manual model setup.

# 1. Download the compose file
curl -fsSL https://raw.githubusercontent.com/manojisnow/boox/main/docker-compose.release.yml \
  -o docker-compose.boox.yml

# 2. Run it
docker compose -f docker-compose.boox.yml up

Open http://localhost:8080⁠ — done.

⁠Prerequisites

For zero-setup quick start:

• Docker and Docker Compose (that's all!)

For local development:

• Java 21
• Node.js 20+
• Maven
• Ollama⁠ with your preferred model (default: phi4-mini)

⁠Development Options

⁠Option 1: Docker Compose from Source (Contributors / Developers)

Builds the image locally from source. Use this if you are making code changes and want to test the full stack end-to-end. Requires cloning the repository.

1. Ensure Docker Desktop is running.

2. From the project root, run:

# Build and start everything
docker compose up -d

# View logs
docker compose logs -f

After the containers are up and running, you'll need to download the phi4-mini model:

# Get the Ollama container ID
docker compose ps

# Download the phi4-mini model
docker exec <ollama_container_id> ollama pull phi4-mini

The Ollama model will be cached in a Docker volume and won't need to be downloaded again.

The frontend is compiled and served directly by the Spring Boot backend — there is only one server. Open your browser and go to: http://localhost:8080⁠

⁠Bonus:

If you have enough resources and want to download a different model, you can do so by running the following command:

docker exec <ollama_container_id> ollama pull <model_name>

⁠Option 2: Local Development

1. Start Ollama server and pull the model:

ollama serve
ollama pull phi4-mini

You can download a different model by replacing phi4-mini with your desired model name. Be considerate of your system resources, as some models can be quite large.

1. Start the backend:

cd backend/chatapp
mvn spring-boot:run

1. Start the frontend:

cd frontend
npm install
npm start

⁠Option 3: Docker + Local Ollama

If you prefer to run Ollama locally (useful if you use Ollama for other projects) but want to containerize the Boox application:

1. Start Ollama locally and pull the model:

ollama serve
ollama pull phi4-mini

1. Run the Boox container with host network access:

docker run -d --name boox_app \
  -p 8080:8080 \
  -v boox_data:/app/data \
  -e OLLAMA_API_URL=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=phi4-mini \
  boox

This setup is particularly useful if you:

• Already have Ollama running locally
• Use Ollama with other applications
• Want to manage Ollama models separately
• Need to switch between different Ollama versions

⁠Option 4: Hybrid Setup (Local App + Docker Ollama)

If you want to run the application locally but use Ollama in Docker:

# Start only Ollama
docker compose up -d ollama

# Then run backend and frontend locally as in Option 2

⁠Configuration

⁠Docker Compose Environment Variables

Create a .env file to customize the setup:

OLLAMA_MODEL=codellama      # Use a different model
OLLAMA_API_TEMPERATURE=0.5  # Adjust temperature

⁠Manual Configuration

When running services separately, you can configure:

docker run -d --name boox_app \
  -p 8080:8080 \
  -v boox_data:/app/data \
  -e OLLAMA_API_URL=http://ollama:11434 \
  -e OLLAMA_MODEL=phi4-mini \
  -e OLLAMA_API_TEMPERATURE=0.7 \
  boox

Available variables:

• OLLAMA_API_URL: Ollama server URL
• OLLAMA_MODEL: AI model to use (default: phi4-mini)
• OLLAMA_API_TEMPERATURE: Model temperature (default: 0.7)
• PORT: Backend port (default: 8080)
• CORS_ALLOWED_ORIGINS: CORS origins (default: http://localhost:3000⁠)
• BOOX_DB_PATH: SQLite database file path (default: /app/data/boox.db in Docker, ./data/boox.db locally) — conversation history is stored here
• OLLAMA_CONTEXT_MAX_TOKENS: token budget for what's sent to the model each turn (default: 3000); older messages are folded into a running summary rather than dropped
• OLLAMA_CONTEXT_SUMMARY_ENABLED: whether to summarize messages that fall out of the context window (default: true)
• OLLAMA_CONTEXT_NUM_CTX: if set (>0), passed to Ollama as options.num_ctx to size the model's own context window

⁠Project Structure

boox/
├── backend/           # Spring Boot backend
│   └── chatapp/          # Main application module
├── frontend/         # React frontend
├── scripts/          # Utility scripts
└── docker-compose.yml # Complete development environment

⁠Features

⁠Chat

• Real-time streaming — responses appear token by token via SSE (Server-Sent Events), with a toggle to switch to non-streaming mode
• Markdown rendering — bot replies render as rich markdown with syntax-highlighted code blocks (via react-markdown + react-syntax-highlighter)
• System prompt — collapsible gear icon in the input bar lets you set a custom system instruction (e.g. "You are a pirate"); persisted across page reloads via sessionStorage
• Context reset — clear the current conversation's messages without restarting the server
• Multi-model support — switch between any models pulled into Ollama at any point; switching mid-conversation continues the same conversation rather than starting a new one
• Context window management — long conversations stay fast and coherent: once a conversation exceeds a token budget, older turns are automatically folded into a running summary instead of being sent to the model in full every turn. The full conversation is always still stored and shown — only what's sent to the model is trimmed. Configurable via OLLAMA_CONTEXT_* (see Manual Configuration⁠)
• Image input — attach up to 4 images to a message for vision-capable models (e.g. gemma3/gemma4); the attach button only appears when the selected model reports vision support. Images persist with the conversation and are shown again on resume

⁠Conversation History

• Persistent, resumable conversations — every conversation is saved to a local SQLite database and survives app restarts and container recreation
• Sidebar — lists all conversations (newest first); click to resume, rename inline, or delete
• Auto-titled — each conversation is titled from your first message

⁠Tool Calling

• Web search — powered by the DuckDuckGo Instant Answer API; the model can look up facts and entities on its own when needed
• Live tool call cards — while the model is searching, a pulsing card appears in the chat; it expands with the result once done
• Extensible framework — add new tools by implementing the Tool interface and registering as a Spring @Component; no other wiring needed

To enable web search, set in backend/chatapp/src/main/resources/application.properties:

tools.websearch.enabled=true

⁠UI / UX

• Dark mode — automatic via prefers-color-scheme, no toggle needed
• 25 CSS design tokens — consistent spacing, colours, radii, and transitions throughout
• Auto-resize textarea — input grows as you type, capped at 120px
• Enter to send, Shift+Enter for newline
• Typing indicator — animated dots while waiting for the first token
• Toast notifications — errors auto-dismiss after 5 seconds
• Accessible — aria-label on all interactive elements

⁠Development Notes

• Frontend runs in development mode with hot-reload (Vite)
• Backend uses Spring Boot with embedded Tomcat and a bounded SSE thread pool (AsyncConfig)
• Conversation history is persisted to a local SQLite database (via Spring Data JPA), not kept in memory — it survives restarts
• Docker Compose provides complete environment; Ollama models and conversation history are each cached in their own Docker volume
• The production container runs as a dedicated non-root user
• Quality gates: JaCoCo ≥ 90% coverage · SpotBugs · Checkstyle (Google Java Style) · PMD · Spotless

⁠Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.