System Coordination

Key files and services that coordinate the AI Platform ecosystem
Published

April 15, 2026

This page describes the “nervous system” of the platform — the canonical files, services, and conventions that make the 60+ ai-* packages work together.

See also: Architecture for system diagrams · platform/AGENTS.md for the agent guide.

1. Network & Ports

  • Port registry: ~/ai-mac-studio/platform/config/routes.yaml + projects/registry.json
  • Key range: 5000–5999 (ai-platform exclusive)
  • CLI: ae-platform port list | check | register | audit
  • Exceptions: INQUA services on 8080/8081; AI Scheduler on 8200

Before assigning any port, check routes.yaml and consult the Port Assignments page.

2. Shared Code

  • Location: ~/ai-mac-studio/platform/shared/
  • Purpose: Python code shared across packages to avoid duplication
Module Contents
shared.database SQLAlchemy base models, connection factory
shared.models Data classes: Person, Project, Document
shared.clients Gemini wrapper via google-genai
shared.mcp MCP server patterns

Import from any package:

from shared.database import Base, get_session
from shared.models import Document

3. Path Resolution

  • Location: ~/ai-mac-studio/platform/lib/env.py
  • Purpose: Machine-portable path resolution based on machines/*.json
from lib.env import platform_env

platform_env.PLATFORM_DIR           # ~/ai-mac-studio/platform/ (→ ai-mac-studio/ai-platform)
platform_env.machine_id             # "mac-studio" | "mac-m4" | "mac-mini" | "openscience"
platform_env.package_dir("ai-viewer")   # ~/ai-mac-studio/ai-agents/document-processing/ai-viewer
platform_env.package_data("ai-voicememo")  # .../ai-voicememo/data

Domain paths (all resolve through the encapsulation symlinks on mac-studio):

from pathlib import Path
AGENTS_DIR      = Path.home() / "ai-agents"      # → ai-mac-studio/ai-agents
SCHOLARLY_DIR   = Path.home() / "ai-scholarly"   # → ai-mac-studio/ai-scholarly
PLATFORM_DIR    = Path.home() / "ai-platform"    # → ai-mac-studio/ai-platform

PROJECT_BASE is deprecated on mac-studio (defaults to $HOME). Use platform_env.package_dir(name) or Path.home() / "ai-agents" / … in all new code.

4. Data Schemas

  • DTD schemas: ~/ai-mac-studio/agents/document-processing/ai-scholar/src/ai_scholar/schemas/
  • Purpose: XML validation for PDAI documents (transcripts, letters, reports)
  • JSON schemas: Validate configurations and API payloads

See XML Schemas for the full PDAI schema reference.

5. Service Management

Background services run as macOS LaunchAgents:

  • Location: ~/Library/LaunchAgents/com.ai-platform.*.plist
  • Pattern: Each package has its own plist; services point to canonical paths

See LaunchD Services for the complete service registry.

6. Project Catalog (DuckDB)

Three DuckDB catalogs provide machine-readable project registers:

File Contents
~/ai-mac-studio/agents/index.duckdb 40 tool packages
~/ai-mac-studio/scholarly/index.duckdb 21 research projects
~/ai-mac-studio/publication/index.duckdb 7 publication items

Query via MCP (ai-catalog tools) or CLI:

python3 ~/ai-mac-studio/agents/index_catalog.py   # refresh all

7. Build Standards

Standard Requirement
Python >= 3.14
Build backend hatchling
AI client google-genai
Database SQLAlchemy 2.0+

Quick Reference

Component Canonical Location Purpose
Port assignments config/routes.yaml Service port registry
Path resolver lib/env.py Machine-portable paths
Shared code shared/ Common Python modules
DTD schemas ai-scholar/src/ai_scholar/schemas/ XML validation
Services ~/Library/LaunchAgents/ Background tasks
Project catalog ~/ai-mac-studio/agents/index.duckdb Project register
Machine configs machines/*.json Per-machine settings

Last updated: 2026-04-15