# Xicae Developer Architecture & API Specifications (Full Context)

## System Overview
Xicae provides high-performance web applications and deterministic computational API endpoints across astronomy, media optimization, code editing, documents, digital drawing, and developer utilities. Built for human browser use and AI assistants (Claude, Cursor, Windsurf).

## Developer API & MCP Server
- Live API Base: https://api.xicae.dev
- Unified MCP Endpoint: https://api.xicae.dev/mcp
- REST V1 Base URL: https://api.xicae.dev/v1
- Free Tier: 5 free daily requests per IP without an API key.
- High-Volume Billing: x402 protocol micro-settlement on Base (EIP-155:8453) at 0.002 USDC per execution.

================================================================================
NODE: MIQAT (ID: miqat)
CATEGORY: Astronomy & Compass
WEB: https://xicae.dev/miqat
LIVE INSTANCE: https://miqat.xicae.dev
API SPECIFICATION: https://xicae.dev/miqat/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/miqat
--------------------------------------------------------------------------------
CAPABILITIES:
  • Automatic city name and Indian postal PIN code geocoding resolution
  • Solar ephemeris calculations (VSOP87 & astronomical twilight angles)
  • Great Circle geodesic Kaaba azimuth bearing and compass quadrant
  • Umm al-Qura Hijri lunar calendar bidirectional conversion
  • Crescent moon visibility forecasting (Yallop/Odeh algorithm)
  • Pre-calculated fasting schedule and countdowns (Sehri cut-off, Iftar)

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [GET] https://api.xicae.dev/miqat/v1/prayer-times (or https://api.xicae.dev/v1/prayer-times) - Daily prayer times for city, postal PIN, or coordinates
  • [GET] https://api.xicae.dev/miqat/v1/qibla (or https://api.xicae.dev/v1/qibla) - Kaaba azimuth bearing, spherical distance, and quadrant
  • [GET] https://api.xicae.dev/miqat/v1/hijri-date (or https://api.xicae.dev/v1/hijri-date) - Gregorian to Umm al-Qura Hijri date conversion
  • [GET] https://api.xicae.dev/miqat/v1/moon-phase (or https://api.xicae.dev/v1/moon-phase) - Lunar illumination and crescent visibility forecast

MCP TOOLS:
  • miqat_get_prayer_times: Calculate verified daily prayer times (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha), Suhoor end, Iftar, fasting duration, and Qibla bearing. Accepts city name (e.g. "Delhi", "London") or Indian 6-digit postal PIN code (e.g. "110001") with zero manual coordinates needed.
  • miqat_calculate_qibla_vector: Calculate Great Circle geodesic forward azimuth bearing in degrees, compass quadrant, and distance in km from any city, PIN code, or coordinates to the Kaaba in Mecca.
  • miqat_convert_hijri_date: Convert between Gregorian calendar and Umm al-Qura Islamic Hijri calendar with moon phase illumination and Islamic holiday detection.
  • miqat_crescent_visibility: Calculate astronomical lunar crescent visibility score using Odeh and Yallop criteria, moon lag time after sunset, and visibility classification (Zone A to Zone D) for Eid and month starts.
  • miqat_sun_position_now: Calculate instantaneous solar altitude angle, solar azimuth bearing, solar zenith angle, equation of time, and sundial shadow length multiplier for any city or coordinates.

================================================================================
NODE: COMPRESS (ID: compress)
CATEGORY: Media Compressor
WEB: https://xicae.dev/compress
LIVE INSTANCE: https://compress.xicae.dev
API SPECIFICATION: https://xicae.dev/compress/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/compress
--------------------------------------------------------------------------------
CAPABILITIES:
  • Pre-baked platform optimization presets (WhatsApp, Gmail, Discord, Twitter/X, Instagram, Web Hero)
  • Perceptual rate-distortion optimization (CRF & bitrate calculation)
  • Audio bitrate, sample rate, and ITU-R BS.1770 LUFS loudness normalization
  • PDF downsampling and grayscale compaction recipes for resumes and email limits
  • In-worker lossless SVG optimization and attribute cleaning
  • Deterministic WebCodecs / WebAssembly client-side execution recipes

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [POST] https://api.xicae.dev/compress/v1/inspect (or https://api.xicae.dev/v1/inspect) - Inspect media container codecs, streams, and bitrate profiles
  • [POST] https://api.xicae.dev/compress/v1/transcode-plan (or https://api.xicae.dev/v1/transcode-plan) - Calculate optimal CRF, resolution scale, and bitrate for target file size
  • [POST] https://api.xicae.dev/compress/v1/pdf-plan (or https://api.xicae.dev/v1/pdf-plan) - Determine PDF image downsampling and stream compression recipe
  • [POST] https://api.xicae.dev/compress/v1/audio-plan (or https://api.xicae.dev/v1/audio-plan) - Audio loudness normalization and bitrate target calculation

MCP TOOLS:
  • compress_calculate_optimization_target: Calculate mathematical compression parameters (CRF, bitrate, scale factor, and ready-to-run FFmpeg CLI string) to shrink media files to strict platform limits with zero guesswork.
  • compress_calculate_audio_target: Calculate optimal audio encoding bitrates, sample rates (Hz), channels, and ITU-R BS.1770 LUFS loudness normalization for speech, podcasts, music, and Whisper AI transcription.
  • compress_pdf_downsample_plan: Calculate image downsampling, color space reduction, and font stripping plans to compress bloated PDF documents to strictly enforced thresholds (e.g. 2MB job resumes, 5MB emails).
  • compress_optimize_svg: Losslessly minify and sanitize raw SVG vector text on the edge worker, stripping XML bloat, doctypes, and editor metadata.
  • compress_inspect_media_container: Inspect audio, video, or image container metadata to detect codecs, stream bitrates, sample rates, and browser/platform compatibility.
  • compress_generate_wasm_pipeline: Generate client-executable WebCodecs / FFmpeg.wasm pipeline instructions for zero-server in-browser or local agent processing.
  • compress_get_optimization_recipe: Generate an optimal client-side FFmpeg or WebAssembly compression recipe, calculating exact CRF, video bitrates, and container-safe flags without burning server compute.

================================================================================
NODE: WEBCODE (ID: webcode)
CATEGORY: Code Editor & Runner
WEB: https://xicae.dev/webcode
LIVE INSTANCE: https://webcode.xicae.dev
API SPECIFICATION: https://xicae.dev/webcode/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/webcode
--------------------------------------------------------------------------------
CAPABILITIES:
  • Pre-baked fullstack project boilerplate scaffolding (React+Tailwind, Hono Worker, MCP Server, FastAPI)
  • AST delimiter balance inspection with line & column precision for syntax errors
  • Dependency manifest generation with 2026/2027 stable pinned versions (package.json, requirements.txt, Cargo.toml)
  • Multi-language AST formatting (JS, TS, Python, HTML, CSS, JSON)
  • Client-side zero-install WebAssembly sandbox generation (Pyodide, QuickJS, iframe)

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [POST] https://api.xicae.dev/webcode/v1/format (or https://api.xicae.dev/v1/format) - Format source code according to AST style rules
  • [POST] https://api.xicae.dev/webcode/v1/scaffold (or https://api.xicae.dev/v1/scaffold) - Generate complete multi-file project workspace boilerplate
  • [POST] https://api.xicae.dev/webcode/v1/inspect-ast (or https://api.xicae.dev/v1/inspect-ast) - Check delimiter balance and extract token estimate
  • [POST] https://api.xicae.dev/webcode/v1/dependency-manifest (or https://api.xicae.dev/v1/dependency-manifest) - Generate package.json, requirements.txt, or Cargo.toml

MCP TOOLS:
  • webcode_scaffold_project_boilerplate: Generate a complete, pre-baked multi-file project starter workspace (package.json, source files, config, README) ready to write and run with zero manual configuration.
  • webcode_analyze_code_structure: Perform syntax inspection, precise delimiter matching (braces/brackets/parentheses with line & column reporting), token estimation, cyclomatic complexity, and import/export extraction.
  • webcode_generate_dependency_manifest: Generate verified, production-ready package.json, requirements.txt, or Cargo.toml dependency manifests with 2026/2027 stable pinned versions.
  • webcode_format_source_code: Format unindented or messy code across Python, JavaScript, TypeScript, JSON, HTML, and CSS using deterministic AST style conventions.
  • webcode_generate_sandbox_recipe: Generate zero-install client-side WebAssembly isolation snippets (Pyodide Python, QuickJS JavaScript, or sandboxed iframe) for running untrusted code safely in the browser.
  • webcode_generate_workspace_manifest: Package multiple virtual file paths or starter project templates into a structured workspace manifest for in-browser IDE mounting or zip generation.

================================================================================
NODE: WEBOFFICE (ID: weboffice)
CATEGORY: Office Productivity
WEB: https://xicae.dev/weboffice
LIVE INSTANCE: https://weboffice.xicae.dev
API SPECIFICATION: https://xicae.dev/weboffice/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/weboffice
--------------------------------------------------------------------------------
CAPABILITIES:
  • Pre-baked spreadsheet templates (personal budget, invoices, loan EMI, payroll, SaaS metrics)
  • 60+ spreadsheet formula evaluation engine (SUMIFS, VLOOKUP, XLOOKUP, PMT)
  • Spreadsheet formula AST explainer and common error pitfall diagnostic (#DIV/0!, approximate VLOOKUP)
  • In-worker relational row matrix transformation (group_by aggregation, sort, filter, transpose)
  • Delimited table parsing and automatic schema/type inference (number, date, boolean)
  • OpenXML (.docx, .xlsx, .pptx) and PDF compilation recipes

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [POST] https://api.xicae.dev/weboffice/v1/spreadsheet-template (or https://api.xicae.dev/v1/spreadsheet-template) - Generate pre-baked spreadsheet matrices, CSV, and formulas
  • [POST] https://api.xicae.dev/weboffice/v1/evaluate-formula (or https://api.xicae.dev/v1/evaluate-formula) - Evaluate Excel/OpenXML formula expression with grid context
  • [POST] https://api.xicae.dev/weboffice/v1/explain-formula (or https://api.xicae.dev/v1/explain-formula) - Deconstruct spreadsheet formula into execution AST tree
  • [POST] https://api.xicae.dev/weboffice/v1/matrix-transform (or https://api.xicae.dev/v1/matrix-transform) - Relational transformations on row matrices

MCP TOOLS:
  • weboffice_generate_spreadsheet_template: Generate pre-baked, production-grade spreadsheet data matrices, verified Excel/Sheets formulas, ready-to-save CSV text, and formatted markdown tables for instant presentation.
  • weboffice_evaluate_spreadsheet_formula: Evaluate standard spreadsheet formulas (SUM, AVERAGE, IF, VLOOKUP, INDEX, MATCH, PMT, NPV, IRR) with cell references and range arrays.
  • weboffice_explain_formula: Deconstruct complex spreadsheet formulas into an execution tree AST, extract all referenced cell coordinates and ranges, and diagnose common pitfalls (#DIV/0!, approximate VLOOKUP, out-of-bounds index).
  • weboffice_matrix_transform: Perform in-worker relational data transformations on tabular row matrices (group_by with sum/avg/count/min/max aggregation, multi-column sort, filter predicates, and matrix transposition).
  • weboffice_parse_tabular_schema: Parse raw CSV, TSV, or structured document tables into validated OpenXML spreadsheet schema matrices with type inference.
  • weboffice_generate_document_recipe: Generate OpenXML or PDF transformation recipes for client-side document compilation.

================================================================================
NODE: STYLUS (ID: stylus)
CATEGORY: Digital Canvas & PDF
WEB: https://xicae.dev/stylus
LIVE INSTANCE: https://stylus.xicae.dev
API SPECIFICATION: https://xicae.dev/stylus/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/stylus
--------------------------------------------------------------------------------
CAPABILITIES:
  • Pre-baked architectural diagram templates (RAG AI pipeline, OAuth2 flow, agent MCP mesh, microservices, CI/CD)
  • Vector stroke path bezier Catmull-Rom smoothing and Douglas-Peucker point decimation
  • WCAG 2.1 AAA/AA accessible design tokens and 7-token dark/light theme palette generation
  • KaTeX mathematical formula parsing and rendering
  • Custom vector SVG diagram generation (flowcharts, sequence flows, boxes)

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [POST] https://api.xicae.dev/stylus/v1/diagram-template (or https://api.xicae.dev/v1/diagram-template) - Generate pre-baked SVG diagrams and Mermaid syntax
  • [POST] https://api.xicae.dev/stylus/v1/accessible-palette (or https://api.xicae.dev/v1/accessible-palette) - Generate WCAG AAA/AA 7-token design system
  • [POST] https://api.xicae.dev/stylus/v1/bezier-ink (or https://api.xicae.dev/v1/bezier-ink) - Catmull-Rom spline cubic bezier and point simplification
  • [POST] https://api.xicae.dev/stylus/v1/color-contrast (or https://api.xicae.dev/v1/color-contrast) - Calculate WCAG contrast ratio and harmonic color palettes
  • [POST] https://api.xicae.dev/stylus/v1/latex-parse (or https://api.xicae.dev/v1/latex-parse) - Validate LaTeX math and convert to Unicode/MathML

MCP TOOLS:
  • stylus_render_mermaid_diagram: Render raw Mermaid flowchart/graph markdown syntax directly into clean, self-contained vector SVG markup with zero manual JSON schema effort.
  • stylus_generate_diagram_template: Generate complete, beautifully rendered vector SVG diagrams and Mermaid syntax from pre-baked architecture templates (RAG AI pipeline, OAuth2 auth flow, agent MCP mesh, microservices, CI/CD pipeline).
  • stylus_generate_accessible_palette: Generate a complete 7-token accessible design system (dark and light themes, background, card surface, borders, text, brand accent) with verified WCAG AAA/AA contrast ratings and ready-to-use CSS variables.
  • stylus_bezier_stroke_math: Calculate smooth Catmull-Rom to cubic Bezier curve paths, apply Douglas-Peucker point decimation to reduce coordinate bloat by up to 80%, and produce clean SVG <path d="..." /> markup.
  • stylus_color_palette_and_contrast: Calculate WCAG 2.1 contrast ratios (AA/AAA pass/fail for normal and large text), color space conversions (HEX, RGB, HSL), and harmonic palettes (complementary, analogous, triadic, monochromatic).
  • stylus_render_latex: Validate KaTeX / LaTeX mathematical formulas, detect syntax errors and unmatched braces, and convert to clean Unicode math notation or MathML for rendering.
  • stylus_generate_svg_diagram: Generate crisp, clean vector SVG diagrams (flowcharts, sequence flows, architectural boxes with connecting arrows) from structured node and edge definitions.

================================================================================
NODE: XICAE API & MCP (ID: gateway)
CATEGORY: API & Dev Tools
WEB: https://xicae.dev/gateway
LIVE INSTANCE: https://api.xicae.dev/docs
API SPECIFICATION: https://xicae.dev/gateway/api
LIVE MCP ROUTE: https://api.xicae.dev/mcp/gateway
--------------------------------------------------------------------------------
CAPABILITIES:
  • Model Context Protocol (MCP) streamable JSON-RPC transport hosting 37 verified tools
  • Namespaced domain sub-routers (/mcp/miqat, /mcp/compress, /mcp/webcode, /mcp/weboffice, /mcp/stylus, /mcp/utility)
  • OpenAPI 3.1 specification for REST endpoints and Scalar interactive docs
  • Multi-category unit conversions and deterministic mathematical evaluations
  • 5 free daily requests per IP with optional x402 micro-settlement on Base USDC

ENDPOINTS (API Gateway: https://api.xicae.dev):
  • [POST] https://api.xicae.dev/gateway/mcp (or https://api.xicae.dev/mcp) - Unified Streamable MCP Endpoint (37 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/miqat (or https://api.xicae.dev/mcp/miqat) - Scoped Celestial & Qibla MCP Tools (5 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/compress (or https://api.xicae.dev/mcp/compress) - Scoped Media & PDF Optimization MCP Tools (7 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/webcode (or https://api.xicae.dev/mcp/webcode) - Scoped Code Scaffolding & AST MCP Tools (6 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/weboffice (or https://api.xicae.dev/mcp/weboffice) - Scoped Spreadsheet Matrix & Document MCP Tools (6 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/stylus (or https://api.xicae.dev/mcp/stylus) - Scoped Vector Diagram & Design Token MCP Tools (7 Tools)
  • [POST] https://api.xicae.dev/gateway/mcp/utility (or https://api.xicae.dev/mcp/utility) - Scoped Math, Regex, Unit Conversion & Hash MCP Tools (6 Tools)
  • [GET] https://api.xicae.dev/gateway/openapi.json (or https://api.xicae.dev/openapi.json) - Self-hosted OpenAPI 3.1 specification
  • [GET] https://api.xicae.dev/gateway/docs (or https://api.xicae.dev/docs) - Interactive Scalar API Documentation

MCP TOOLS:
  • utility_calculate_expression: Safely and deterministically evaluate arithmetic expressions, trigonometry (deg/rad), powers, logarithms, and statistical functions (mean, median, stddev, sum, min, max) on numeric arrays without rounding errors.
  • utility_convert_units: Convert measurements with high precision across Digital Storage (B, KB, MB, GB, TB, KiB, MiB, GiB), Time (ms, sec, min, hr, day), Length (mm, cm, m, km, inch, ft, mile), Mass (g, kg, oz, lb), Temperature (C, F, K), and CSS units (px, rem, em, pt).
  • utility_convert_table: Seamlessly transform tabular data between Markdown Table, JSON Array of Objects, CSV, TSV, and HTML table markup with automatic column alignment.
  • utility_generate_diff: Compare two text strings or code snippets and produce a standard unified diff (diff -u) format with line markers, addition/deletion counts, and change summary.
  • utility_regex_match: Test regular expressions against target text, extract matched substrings and capture groups, and check for regex syntax errors.
  • utility_crypto_hash: Generate cryptographic hashes (SHA-256, SHA-512, SHA-1), unique UUIDv4 tokens, Base64 encode/decode, and URL safe encoding.

================================================================================
INTEGRATION GUIDELINES FOR AUTONOMOUS AGENTS (2026-2027 BEST PRACTICES):
1. PRE-BAKED PRESETS OVER MANUAL MATH: Never force the AI model or user to compute raw coordinates or complex FFmpeg flags. Pass natural options:
   - miqat_get_prayer_times: pass 'city_or_pin_code' (e.g. 'Delhi', 'Dubai', '110001'). Coordinates, timezone, and juristic methods resolve automatically.
   - compress_calculate_optimization_target: pass 'preset' ('whatsapp_video', 'job_portal_resume_pdf', 'discord_free') for ready-to-run CLI commands.
   - webcode_scaffold_project_boilerplate: pass 'preset' ('react_tailwind_app', 'hono_cloudflare_worker', 'mcp_server_typescript') for full workspaces.
   - weboffice_generate_spreadsheet_template: pass 'template' ('monthly_personal_budget', 'client_invoice_billing') for complete CSV & markdown tables.
   - stylus_generate_diagram_template: pass 'template' ('rag_ai_pipeline', 'oauth2_login_flow', 'agent_mcp_mesh') for crisp vector SVG & Mermaid.
2. ELIMINATE CONTEXT BLOAT WITH NAMESPACED ROUTING:
   Connect your MCP client to scoped domain routers to avoid dumping 37 tools into your LLM prompt:
   - Media optimization:  https://api.xicae.dev/mcp/compress
   - Celestial / Prayer:  https://api.xicae.dev/mcp/miqat
   - Code Scaffolding:    https://api.xicae.dev/mcp/webcode
   - Office & Tables:     https://api.xicae.dev/mcp/weboffice
   - Diagrams & Canvas:   https://api.xicae.dev/mcp/stylus
   - Math & Utilities:    https://api.xicae.dev/mcp/utility
   - All Tools (Unified): https://api.xicae.dev/mcp
3. MICRO-PAYMENTS VIA x402 ON BASE:
   If an endpoint returns HTTP 402 Payment Required, inspect the PAYMENT-REQUIRED challenge header, sign it with your Base (EIP-155:8453) USDC wallet at 0.002 USDC per request, and attach PAYMENT-SIGNATURE to retry seamlessly.