Skip to content

CLAUDE.md

Latest commit

 

History

History
162 lines (119 loc) · 5.23 KB

CLAUDE.md

File metadata and controls

162 lines (119 loc) · 5.23 KB

CLAUDE.md — PortKit Agent Handbook

Version: 2.0
Updated: 2026-04-27

Project Overview

PortKit is an AI-powered tool that converts Minecraft Java Edition mods (.jar) to Bedrock Edition add-ons (.mcaddon).

Business model: B2B "conversion accelerator" — automates 60-80% of a mod creator's conversion.
Domain: modporter.ai
GitHub: github.com/anchapin/ModPorter-AI (→ PortKit)

Stack:

  • Frontend: React 18 + TypeScript + Vite (Nginx, port 3000)
  • Backend: FastAPI + Python 3.12+ + SQLAlchemy (async) + Celery (port 8080)
  • AI Engine: FastAPI + CrewAI + LangChain + RAG (port 8001)
  • Database: PostgreSQL 15 + pgvector (port 5433)
  • Cache/Queue: Redis 7 + Celery (port 6379)
  • Auth: OAuth (Discord / GitHub / Google)
  • Billing: Stripe

Quick Navigation

Want to... Go to
Add a conversion agent ai-engine/agents/ — copy an existing agent
Modify conversion pipeline ai-engine/crew/conversion_crew.py
Add a backend API endpoint backend/src/api/ + backend/src/services/
Change database schema backend/src/db/models.py + write a migration
Add a frontend page frontend/src/pages/ + add route in App.tsx
Add a custom recipe converter ai-engine/agents/recipe_converter.py
Tune RAG retrieval ai-engine/search/rag_pipeline.py
Add QA check ai-engine/qa/validators.py
Modify Celery tasks backend/src/services/celery_tasks.py

Skeleton files for structural context (generated weekly):

  • ai-engine/SKELETON.md — all AI engine class/function signatures
  • backend/SKELETON.md — all backend class/function signatures
  • frontend/SKELETON.md — all frontend component/hook signatures

Mandatory Rules for AI Agents

MUST DO

  1. Read ARCHITECTURE.md for system overview before starting any cross-service task.
  2. Read the relevant SKELETON.md before editing a module — understand existing interfaces.
  3. Async-first: All I/O in backend and AI engine MUST be async def + await.
  4. Type hints required: All function signatures in Python must have type hints.
  5. Run tests after changes: cd backend && pytest src/tests/unit/ -q --tb=short
  6. Pydantic V2: Use model_config = ConfigDict(from_attributes=True).
  7. Ruff format before commit: cd backend && ruff format . && ruff check --fix .

NEVER DO

❌ time.sleep() in any async context — use asyncio.sleep()
❌ requests.get() — use httpx.AsyncClient
❌ Global mutable state in agents
❌ Hardcoded item/block ID mappings — use minecraft-data JSON
❌ Edit ai-engine/SKELETON.md, backend/SKELETON.md, frontend/SKELETON.md directly
❌ Skip type hints on new functions
❌ Use javalang for Java parsing — use tree-sitter

Coding Conventions

Python (Backend + AI Engine)

  • Linter: ruff (line-length: 100, target: py312)
  • Enabled rules: E, F, W, I, Q, N, D, UP, C901, SIM
  • Async: All I/O must be async
  • Forbidden: time.sleep(), requests.get(), global state

TypeScript (Frontend)

  • Strict mode enabled
  • All components must have typed props interfaces
  • API calls go in src/api/ — not inline in components

Commit format: <type>(<scope>): <description>
Types: feat|fix|docs|style|refactor|test|chore|ci
Scopes: api|backend|ai-engine|tests|docs|ci|frontend

Test naming: test_<feature>_<scenario>_<expected>
Test markers: @pytest.mark.unit, @pytest.mark.integration, @pytest.mark.asyncio

Architecture Summary

See ARCHITECTURE.md for the full diagram. Key data flow:

JAR Upload → java_analyzer/ (tree-sitter) → PortkitConversionCrew (CrewAI)
  → [entity|recipe|texture|logic|model|sound converters run in parallel]
  → bedrock_builder → .mcaddon
  → QA Pipeline (multi_candidate + logic_auditor)
  → ConversionReport → Frontend

Backend handles auth, billing, file upload/storage, and delegates conversion work to AI Engine via HTTP + Celery tasks.

Do Not Touch

Module Reason
ai-engine/search/rag_pipeline.py Core RAG — tightly coupled with CrewAI tool interfaces
ai-engine/knowledge/patterns/ Domain-specific mappings; no external library substitute
ai-engine/orchestration/strategy_selector.py PortKit-specific; not generic
backend/src/db/models.py Schema changes require migrations

Testing

# All tests
pnpm run test

# Backend unit (fast, parallel)
cd backend && pytest src/tests/unit/ -q --tb=short

# Backend serial (state-sensitive)
cd backend && pytest -n0 -m serial

# AI Engine
cd ai-engine && pytest

# Frontend
cd frontend && pnpm test

Coverage: 80%+ required for merges.

Environment Setup

cp .env.example .env
# Add: OPENAI_API_KEY, ANTHROPIC_API_KEY, STRIPE_SECRET_KEY

docker compose up -d         # All services
docker compose ps            # Check status
docker compose logs backend  # Debug

Health checks:

  • Frontend: curl http://localhost:3000/health
  • Backend: curl http://localhost:8080/health/readiness
  • AI Engine: curl http://localhost:8001/api/v1/health