S
S
Back to Projects
Web App2026CompletedFeatured Project

Minecraft Ai

This is a Next.js project bootstrapped with create-next-app. Getting Started First, run the development server: ``bash npm run dev or yarn dev or pnpm dev or bun dev ` Open http://...

Source Code
RoleSole Developer
Classificationhigh
Client / ContextOpen Source Project
Development TimelineCompleted

Technical Architecture & Engineering Overview

Detailed system design and core implementation

Core System Architecture The solution follows a classic client‑server model. The frontend (Next.js + TypeScript) communicates asynchronously with the backend API (FastAPI) over HTTP. The UI renders streamed answers, citation badges, and a WebGL canvas that displays the 3D block generated by the server.

Data Ingestion & RAG Engine Documentation (20 support tickets) is pre‑processed into chunks and indexed by a hybrid RAG engine that combines BM25 keyword matching with TF‑IDF cosine similarity. The get_rag_engine() singleton supplies searchable chunks used by the AgentPipeline to retrieve relevant context for each query.

Execution Flow

  1. The client sends a POST /ask with a natural‑language question.
  2. AgentPipeline routes the request through the Intent Router, applying safety guardrails before invoking the RAG engine.
  3. Retrieved documents are passed to the LLM (not shown) which formulates an answer and may trigger a tool call.
  4. If the tool call is a block generation request, the server executes generate_dynamic_block via the POST /generate_block endpoint, producing a Blockbench JSON, a binary .glb, and a 16×16 PNG texture.
  5. All tool interactions are logged to tool_calls.json for auditability.

Security & Guardrails The Intent Router enforces content policies, filters disallowed queries, and logs every tool invocation. Invalid or empty prompts result in a 400 error, preventing misuse of the generation pipeline.

Build & Deployment Topology Docker Compose defines three services: backend (FastAPI), frontend (Next.js), and a placeholder for a vector store (e.g., Qdrant). Environment variables propagate API keys (e.g., GEMINI_API_KEY). Volumes persist backend logs, and the stack is reachable at http://localhost:3000 for the UI and http://localhost:8000 for the API.

System Diagrams & Flow Visualizations

Interactive Mermaid architecture & execution flows

Architectural Visualizer · System Architecture

Core System Features

Key capabilities & architectural features

FEATURE 01

Core minecraft-ai functionality

Core minecraft-ai functionality

FEATURE 02

Hybrid RAG Q&A engine combining BM25 lexical search with TF-IDF cosine similarity scoring.

Hybrid RAG Q&A engine combining BM25 lexical search with TF-IDF cosine similarity scoring.

FEATURE 03

Agent intent router distinguishing between document inquiries, tool actions, and block generation requests.

Agent intent router distinguishing between document inquiries, tool actions, and block generation requests.

FEATURE 04

Safety guardrail engine evaluating incoming prompts to enforce abstention policies.

Safety guardrail engine evaluating incoming prompts to enforce abstention policies.

FEATURE 05

Procedural 3D Minecraft block generator producing Blockbench Java JSON models and binary .glb assets.

Procedural 3D Minecraft block generator producing Blockbench Java JSON models and binary .glb assets.

FEATURE 06

16x16 pixel-art PNG texture generator customized to descriptive input prompts.

16x16 pixel-art PNG texture generator customized to descriptive input prompts.

FEATURE 07

Interactive WebGL 3D model viewer with 360-degree orbit controls integrated in the Next.js UI.

Interactive WebGL 3D model viewer with 360-degree orbit controls integrated in the Next.js UI.

FEATURE 08

Real-time chat interface displaying grounded document citations and relevance metrics.

Real-time chat interface displaying grounded document citations and relevance metrics.

FEATURE 09

Visual response type badges categorizing outputs as Answer, Abstention, Tool Call, or Guardrail.

Visual response type badges categorizing outputs as Answer, Abstention, Tool Call, or Guardrail.

FEATURE 010

Structured tool execution logging capturing arguments and status in tool_calls.json.

Structured tool execution logging capturing arguments and status in tool_calls.json.

FEATURE 011

Automated evaluation benchmark running 15 evaluation queries against a golden dataset.

Automated evaluation benchmark running 15 evaluation queries against a golden dataset.

FEATURE 012

Multi-container Docker Compose orchestration for full-stack local deployment.

Multi-container Docker Compose orchestration for full-stack local deployment.

FEATURE 013

Grounded Retrieval-Augmented Generation Q&A over Craftify support documentation.

Grounded Retrieval-Augmented Generation Q&A over Craftify support documentation.

FEATURE 014

Hybrid BM25 and TF-IDF cosine similarity vector retrieval engine.

Hybrid BM25 and TF-IDF cosine similarity vector retrieval engine.

FEATURE 015

Procedural 3D Minecraft block asset synthesis from natural language prompts.

Procedural 3D Minecraft block asset synthesis from natural language prompts.

FEATURE 016

Automated 16x16 pixel-art PNG texture generation.

Automated 16x16 pixel-art PNG texture generation.

FEATURE 017

Interactive WebGL 3D model viewer with full 360-degree orbit controls.

Interactive WebGL 3D model viewer with full 360-degree orbit controls.

FEATURE 018

Agent Safety Guardrail engine with automated query abstention capabilities.

Agent Safety Guardrail engine with automated query abstention capabilities.

FEATURE 019

Real-time visual response badges (Answer, Abstention, Tool Call, Guardrail).

Real-time visual response badges (Answer, Abstention, Tool Call, Guardrail).

FEATURE 020

Structured JSON logging for tool invocations and intent routing.

Structured JSON logging for tool invocations and intent routing.

FEATURE 021

Backend health check endpoint (`GET /health`) displaying chunk indexing status.

Backend health check endpoint (`GET /health`) displaying chunk indexing status.

FEATURE 022

Full containerized development and deployment setup via Docker Compose.

Full containerized development and deployment setup via Docker Compose.

FEATURE 023

FastAPI REST API with `/ask`, `/health`, and `/generate_block` endpoints

FastAPI REST API with `/ask`, `/health`, and `/generate_block` endpoints

FEATURE 024

Hybrid BM25 + TF‑IDF RAG search over Craftify documentation

Hybrid BM25 + TF‑IDF RAG search over Craftify documentation

FEATURE 025

Agent Intent Router with safety guardrails and tool call logging

Agent Intent Router with safety guardrails and tool call logging

FEATURE 026

Procedural 3D block generation producing Blockbench JSON, `.glb`, and 16×16 PNG textures

Procedural 3D block generation producing Blockbench JSON, `.glb`, and 16×16 PNG textures

FEATURE 027

Interactive WebGL 3D viewer with 360° orbit controls in the frontend

Interactive WebGL 3D viewer with 360° orbit controls in the frontend

FEATURE 028

Real‑time chat console UI with response‑type badges (Answer, Abstention, Tool Call, Guardrail)

Real‑time chat console UI with response‑type badges (Answer, Abstention, Tool Call, Guardrail)

FEATURE 029

Docker Compose orchestration for backend, frontend, and vector store

Docker Compose orchestration for backend, frontend, and vector store

FEATURE 030

Evaluation harness that runs 15 benchmark queries with 100 % success

Evaluation harness that runs 15 benchmark queries with 100 % success

FEATURE 031

Comprehensive logging of tool executions for auditability

Comprehensive logging of tool executions for auditability

FEATURE 032

TypeScript‑based Next.js frontend with hot‑reload development server

TypeScript‑based Next.js frontend with hot‑reload development server

Engineering Challenges & Solutions

Problem statements & resolution strategies

Challenge #1

Balancing retrieval speed vs. semantic relevance in the hybrid BM25/TF‑IDF engine

Balancing retrieval speed vs. semantic relevance in the hybrid BM25/TF‑IDF engine

Challenge #2

Ensuring safe tool execution while allowing expressive LLM‑driven actions

Ensuring safe tool execution while allowing expressive LLM‑driven actions

Challenge #3

Managing stateful streaming responses over HTTP without WebSocket complexity

Managing stateful streaming responses over HTTP without WebSocket complexity

Challenge #4

Packaging large 3D assets (Blockbench JSON, `.glb`) within a lightweight Docker image

Packaging large 3D assets (Blockbench JSON, `.glb`) within a lightweight Docker image

Challenge #5

Designing a generic logger that captures diverse tool payloads without schema lock‑in

Designing a generic logger that captures diverse tool payloads without schema lock‑in

Challenge #6

Providing a seamless developer experience across Python virtual environments and Docker

Providing a seamless developer experience across Python virtual environments and Docker

API Reference & Endpoints

REST API surface & route documentation

METHODENDPOINT PATHDESCRIPTIONCOPY
GET/Endpoint defined in backend/app/main.py
GET/healthEndpoint defined in backend/app/main.py
POST/generate_blockEndpoint defined in backend/app/main.py
POST/askEndpoint defined in backend/app/main.py

Key Code Modules & Architecture

Core file entrypoints and service responsibilities

BackendMODULE 01
backend

Module component managing backend source logic

AppMODULE 02
frontend/src/app

Module component managing app source logic

DocsMODULE 03
docs

Module component managing docs source logic

FrontendMODULE 04
frontend

Module component managing frontend source logic

ModelsMODULE 05
frontend/public/models

Module component managing models source logic

SrcMODULE 06
frontend/src

Module component managing src source logic

ComponentsMODULE 07
frontend/src/components

Module component managing components source logic

User Journey Pipeline

  1. 1User accesses application user interface via browser
  2. 2User triggers action invoking HTTP/WebSocket API endpoints

Execution Code Flow

  1. 1Client or caller initiates request to application entrypoint
  2. 2Backend router validates request parameters and applies middleware
  3. 3Application serializes JSON/audio/data response back to client

System FAQ & Technical Specifications

Frequently asked questions and core architecture details

Q: What technologies are used in Minecraft Ai?

Minecraft Ai is engineered using modern full-stack frameworks.

Q: What core engineering problem does Minecraft Ai solve?

This is a Next.js project bootstrapped with create-next-app. Getting Started First, run the development server: ``bash npm run dev or yarn dev or pnpm dev or bun dev ` Open http://...

Q: How is 'Balancing retrieval speed vs. semantic relevance in the hybrid BM25/TF‑IDF engine' resolved in Minecraft Ai?

Resolved through specialized system architecture and resilient state handling.

Related Systems & Case Studies

Explore similar technical architectures and projects

View All Systems

Jobify

React + TypeScript + Vite This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available: - @vite...

Mpulse

Welcome to your Expo app This is an Expo project created with create-expo-app. Get started 1. Install dependencies ``bash npm install ` 2. Start the app `bash npx expo start `` In ...

3d Menu

Routes TanStack Start uses file-based routing. Every .tsx file in this directory defines a route. Do not create src/pages/, src/routes/app/index.tsx, or app/layout.tsx — those are ...

Explore All Projects