diff --git a/README.md b/README.md index 960a698..37934ed 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,54 @@ -# OpenAPI Definition Starter +# 360 Magicians — Docs + +OpenAPI definition and aggregated documentation for the [360 Magicians](https://github.com/360magicians) +Deaf-First AI ecosystem. + +## Project Docs + +See the [`docs/`](./docs/README.md) directory for full project documentation: + +### Ecosystem Guides +- [About 360Magicians](./docs/about.md) +- [Infrastructure / Ecosystem Architecture](./docs/infrastructure.md) +- [Git Workflow & GitHub Integration](./docs/git-workflow.md) +- [Helm Deployment (dev → prod)](./docs/helm.md) +- [Environments & Bootstrap](./docs/environments.md) +- [AI Providers, Vendors & Resources](./docs/providers.md) +- [AI Model Manifest](./docs/ai-model-manifest.md) +- [AI Inference Architecture](./docs/ai-inference.md) +- [Package Managers & Runtimes](./docs/package-managers.md) +- [Triggers, Webhooks & Prompts](./docs/triggers-webhooks.md) +- [Pipeline Handoffs](./docs/pipeline-handoffs.md) +- [Copilot, Bots & Auth Access](./docs/copilot-bots.md) + +### Project Docs +- [DeafAuth](./docs/projects/deafauth.md) +- [PinkSync](./docs/projects/pinksync.md) +- [FibonRose](./docs/projects/fibonrose.md) +- [Municipal DAO](./docs/projects/municipal-dao.md) +- [Railway Next.js Template](./docs/projects/railway-template.md) +- [MBTQ.dev](./docs/projects/mbtq-dev.md) +- [MBTQUniverse](./docs/projects/mbtquniverse.md) + +## OpenAPI Definition + +The `openapi/` directory contains the OpenAPI 3.1 definition for the 360 Magicians API. + +### Install + +1. Install [Node JS](https://nodejs.org/). +2. Clone this repo and run `npm install` in the repo root. + +### Usage + +```bash +# Start reference docs preview +npm start + +# Validate the definition +npm test +``` + ## How to use this starter diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e7cead6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,117 @@ +# 360 Magicians — Documentation + +This directory contains aggregated documentation for the [360Magicians](https://github.com/360magicians) +Deaf-First AI ecosystem and all associated repositories across the MBTQ universe. + +--- + +## Contents + +### Ecosystem Guides + +| File | Description | +|------|-------------| +| [about.md](./about.md) | Organization overview, mission, and project list | +| [infrastructure.md](./infrastructure.md) | MBTQ ecosystem architecture (GCP / Kubernetes) | +| [git-workflow.md](./git-workflow.md) | Branch strategy, agent git flow, GitHub Graph API, CI/CD events | +| [helm.md](./helm.md) | Helm charts, deployment targets, env overrides (dev → prod) | +| [environments.md](./environments.md) | Dev → staging → prod separation, bootstrap steps, env vars | +| [providers.md](./providers.md) | AI providers, platform vendors, open-source vs proprietary vs custom | +| [ai-model-manifest.md](./ai-model-manifest.md) | Canonical AI model registry — HF IDs, capabilities matrix, SDK bindings, deployment paths | +| [ai-inference.md](./ai-inference.md) | Inference servers (vLLM/Ollama/TGI), routing, fallback chains, latency tiers | +| [package-managers.md](./package-managers.md) | pnpm / npm / Deno / Fresh / HTML — which project uses what | +| [triggers-webhooks.md](./triggers-webhooks.md) | Full webhook catalog, GitHub App setup, HMAC verification, prompt triggers | +| [pipeline-handoffs.md](./pipeline-handoffs.md) | Every agent handoff with trigger, input/output contracts, and commands | +| [copilot-bots.md](./copilot-bots.md) | Copilot prompts, authorized bots, OAuth/PAT/JWT/GCP auth access patterns | + +### Project Docs + +| File | Description | +|------|-------------| +| [projects/deafauth.md](./projects/deafauth.md) | DeafAuth — identity & access layer + Magician Jobs API | +| [projects/pinksync.md](./projects/pinksync.md) | PinkSync — accessibility AI middleware + API broker | +| [projects/fibonrose.md](./projects/fibonrose.md) | FibonRose — Next.js UI application (pnpm, shadcn/ui) | +| [projects/municipal-dao.md](./projects/municipal-dao.md) | Municipal DAO — real-time WebSocket governance platform | +| [projects/railway-template.md](./projects/railway-template.md) | Railway Next.js template — production-ready starter (npm) | +| [projects/mbtq-dev.md](./projects/mbtq-dev.md) | MBTQ.dev — AI-powered full-stack development platform | +| [projects/mbtquniverse.md](./projects/mbtquniverse.md) | MBTQUniverse — DAO governance, tokenization, staking | + +--- + +## Repositories Covered + +### 360Magicians Org + +| Repo | Status | Language | +|------|--------|----------| +| [360magicians/about](https://github.com/360magicians/about) | Active | — | +| [360magicians/infrastructure](https://github.com/360magicians/infrastructure) | Active | — | +| [360magicians/deafauth](https://github.com/360magicians/deafauth) | Active | JavaScript | +| [360magicians/pinksync](https://github.com/360magicians/pinksync) | Active | TypeScript | +| [360magicians/fibonrose](https://github.com/360magicians/fibonrose) | Active | TypeScript | +| [360magicians/municipal-dao](https://github.com/360magicians/municipal-dao) | Active | TypeScript | +| [360magicians/railway_nextjs_with_shadcn](https://github.com/360magicians/railway_nextjs_with_shadcn) | Active | TypeScript | + +### pinkycollie + +| Repo | Status | Language | +|------|--------|----------| +| [pinkycollie/mbtq-dev](https://github.com/pinkycollie/mbtq-dev) | Active | TypeScript | +| [pinkycollie/mbtquniverse](https://github.com/pinkycollie/mbtquniverse) | Active | JavaScript | +| [pinkycollie/deaf-first-platform](https://github.com/pinkycollie/deaf-first-platform) | Active | HCL | +| [pinkycollie/Nextjs-DeafAUTH](https://github.com/pinkycollie/Nextjs-DeafAUTH) | Active | TypeScript | +| [pinkycollie/NegraRosa](https://github.com/pinkycollie/NegraRosa) | Active | TypeScript | +| [pinkycollie/VR4Deaf](https://github.com/pinkycollie/VR4Deaf) | Active | TypeScript | +| [pinkycollie/ai-magicians-gcp](https://github.com/pinkycollie/ai-magicians-gcp) | Active | TypeScript | +| [pinkycollie/FibonRoseTrust](https://github.com/pinkycollie/FibonRoseTrust) | Active | TypeScript | +| [pinkycollie/PinkSync-Visualizer](https://github.com/pinkycollie/PinkSync-Visualizer) | Active | TypeScript | +| [pinkycollie/Deaf-Creators-Platform](https://github.com/pinkycollie/Deaf-Creators-Platform) | Active | TypeScript | + +### MBTQ-dev Org + +| Repo | Status | Language | +|------|--------|----------| +| [MBTQ-dev/DeafAUTH](https://github.com/MBTQ-dev/DeafAUTH) | Active | TypeScript | +| [MBTQ-dev/Magician_Platform](https://github.com/MBTQ-dev/Magician_Platform) | Active | TypeScript | +| [MBTQ-dev/DEAF-FIRST-PLATFORM2](https://github.com/MBTQ-dev/DEAF-FIRST-PLATFORM2) | Active | HCL | +| [MBTQ-dev/deploy-admin](https://github.com/MBTQ-dev/deploy-admin) | Active | TypeScript | +| [MBTQ-dev/Auto-API](https://github.com/MBTQ-dev/Auto-API) | Active | Python | +| [MBTQ-dev/pinksync-starter](https://github.com/MBTQ-dev/pinksync-starter) | Active | Python | + +### DeafAUTH Org + +| Repo | Status | Language | +|------|--------|----------| +| [DeafAUTH/readme.md](https://github.com/DeafAUTH/readme.md) | Active | — | + +### PinkSync Org + +| Repo | Status | Language | +|------|--------|----------| +| [PinkSync/PinkSync](https://github.com/PinkSync/PinkSync) | Active | TypeScript | +| [PinkSync/Core-principles](https://github.com/PinkSync/Core-principles) | Active | Python | +| [PinkSync/pinksync-starter](https://github.com/PinkSync/pinksync-starter) | Active | — | +| [PinkSync/awesome-deaf-first](https://github.com/PinkSync/awesome-deaf-first) | Active | — | +| [PinkSync/manifesto](https://github.com/PinkSync/manifesto) | Active | — | + +--- + +## API Quick Reference + +Base URL: `https://api.360magicians.com` + +```bash +# Authenticate via DeafAUTH +export DEAFAUTH_TOKEN= + +# List jobs +curl -H "Authorization: ******" https://api.360magicians.com/jobs/list + +# Submit idea +curl -X POST https://api.360magicians.com/idea \ + -H "Authorization: ******" \ + -d '{"prompt": "Deaf-first SaaS idea"}' +``` + +Full API reference: [DeafAuth Docs](./projects/deafauth.md) + diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..5ad11e0 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,66 @@ +# 👁‍🗨 360 Magicians +**Deaf Aware. Rooted Deaf First. Globally Future-Proof AIs.** + +[![Deaf-First](https://img.shields.io/badge/Deaf%20First-Accessible%20by%20Design-blue?style=flat-square)]() +[![AI Agents](https://img.shields.io/badge/AI%20Agents-360Magicians-green?style=flat-square)]() +[![License](https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square)]() +[![Open Source](https://img.shields.io/badge/Open%20Source-Yes-orange?style=flat-square)]() + +--- + +We are an **anonymous collective** of Deaf-aware and Deaf-First infrastructure architects, +software engineers, AI builders, and agentic system designers. +Our mission: **engineer the future of accessible innovation** — +where Deaf communities aren't "included later," but **built in from day zero**. + +--- + +## 🚀 What We Build + +- **Deaf-First Platforms** → VR4Deaf, PinkSync, DeafAuth, FibonRose +- **AI & Agents** → 360Magicians frameworks that think and act for business +- **Infrastructure** → Compliant, scalable, and globally interoperable + +--- + +## 📌 Repositories + +| Project | Description | +|---------|-------------| +| **`magician-core`** | Central AI agent orchestrating IDEA → BUILD → GROW → MANAGED lifecycle | +| **`pinksync`** | Accessibility layer + real-time sync engine | +| **`deafauth`** | Web2/Web3 authentication & verification for Deaf-first platforms | +| **`mbtq.dev`** | Core developer platform & ecosystem hub | +| **`vr4deaf`** | Partner & milestone tracking platform for Deaf entrepreneurs | +| **`fibonrose`** | Next.js UI application (TypeScript / shadcn/ui) | +| **`municipal-dao`** | On-chain governance DAO with real-time WebSocket voting | +| **`railway_nextjs_with_shadcn`** | Production-ready Next.js Railway deployment template | + +--- + +## 🌐 Connect + +- Website: [360magicians.com](https://360magicians.com) +- Ecosystem Docs: *(Coming Soon)* +- Partners: v0, AI Google Studio, Supabase, OpenAI, Claude AI, Cursor AI, Neon, Fal, Grok, Groq + +--- + +## Lifecycle + +360Magicians orchestrates projects through **IDEA → BUILD → GROW → MANAGED**. Each stage is managed +by specialized AI agents: + +| Stage | Magician Roles | Description | +|---------|--------------------------------------------------|-----------------------------------------------------| +| IDEA | ValidatorMagician, ResearchMagician | Generate ideas, validate compliance, research market | +| BUILD | DeveloperMagician, DesignMagician | Create repo, generate wireframes, develop MVP | +| GROW | GrowthMagician, PartnershipMagician | Marketing, analytics, onboarding | +| MANAGED | ComplianceMagician, FinanceMagician, OpsMagician | Ongoing monitoring, reporting, operations | + +All tasks are **Deaf-first**: ASL-ready interfaces, captions, and accessibility features. + +--- + +> _We don't just build code. +> We build the conditions for Deaf entrepreneurs to lead the next era._ diff --git a/docs/ai-inference.md b/docs/ai-inference.md new file mode 100644 index 0000000..3e42c4d --- /dev/null +++ b/docs/ai-inference.md @@ -0,0 +1,240 @@ +# AI Inference Architecture + +> Inference server options, routing strategy, fallback chains, and latency tiers for the 360 Magicians / MBTQ ecosystem. + +--- + +## Inference Server Options + +| Server | Type | Best For | GPU Required | Supported Models | +|--------|------|----------|:------------:|-----------------| +| **vLLM** | Self-hosted | High-throughput production LLM serving | ✓ | Llama 3, Mistral, Mixtral, CodeLlama | +| **Ollama** | Self-hosted | Local dev, low-config single-GPU | Optional | Llama 3, Mistral, CodeLlama, Whisper | +| **TGI (Text Generation Inference)** | Self-hosted / HF | Production HF models, continuous batching | ✓ | Llama 3, Mistral, Mixtral, BLOOM | +| **llama.cpp** | Self-hosted | CPU-only / edge inference, quantized models | — | GGUF-format models (Llama, Mistral, Phi) | +| **HF Inference API** | HF-hosted | Dev, staging, low-traffic | — | All HF Hub models | +| **HF Dedicated Endpoints** | HF-hosted | Production, SLA-bound | ✓ | All HF Hub models | +| **Groq API** | Cloud API | Ultra-low-latency LLM (LPU hardware) | — | Llama 3, Mixtral | +| **Vertex AI (Gemini)** | Cloud API | Google-integrated production workloads | — | Gemini 1.5 Pro/Flash | +| **OpenAI API** | Cloud API | GPT models, Whisper ASR | — | GPT-4, GPT-4o, Whisper | +| **Anthropic API** | Cloud API | Claude agents, code review | — | Claude 3.5, Claude 3 Haiku | +| **Fal** | Cloud API | Async image/video generation | — | SDXL, FLUX.1, video models | + +--- + +## Inference Routing + +Requests are routed to the appropriate inference tier based on **model requirement**, **latency SLA**, and **environment**: + +``` +Client Request + │ + ▼ +oRPC Inference Gateway (api.360magicians.com/inference/*) + │ + ├─ model prefix "gpt-*" ──► OpenAI API + ├─ model prefix "claude-*" ──► Anthropic API + ├─ model prefix "gemini-*" ──► Vertex AI / AI Studio + ├─ model prefix "groq/*" ──► Groq API + ├─ model prefix "fal/*" ──► Fal API + ├─ model prefix "hf/*" ──► HF Inference API / Dedicated Endpoint + └─ model prefix "local/*" ──► Ollama (dev) / vLLM/TGI (prod K8s) +``` + +### Routing Rules by Stage + +| Environment | LLM Route | Embedding Route | ASR Route | Image-gen Route | +|-------------|-----------|----------------|-----------|----------------| +| **Local dev** | Ollama (Llama 3 8B) | Ollama (MiniLM) | Ollama (Whisper) | HF Serverless (SDXL) | +| **Staging** | Groq (Llama 3 70B) | HF Serverless (BGE) | HF Serverless (Whisper) | Fal | +| **Production** | Vertex AI / OpenAI / Anthropic | HF Dedicated Endpoint (BGE) | HF Dedicated Endpoint (Whisper) | Fal | + +### Per-Service Routing + +| Service | Default LLM | Override Env Var | +|---------|------------|-----------------| +| 360magicians hub | `gemini-1.5-pro` | `HUB_LLM_MODEL` | +| mbtq.dev | `gemini-1.5-flash` | `MBTQ_LLM_MODEL` | +| PinkSync | `mistral-7b-instruct` | `PINKSYNC_LLM_MODEL` | +| DeafAuth | `gemini-1.5-flash` | `DEAFAUTH_LLM_MODEL` | +| Quinn AI | `claude-3-5-sonnet` | `QUINN_LLM_MODEL` | +| Local dev (all) | `AI_MODEL_OVERRIDE` | `AI_MODEL_OVERRIDE` | + +--- + +## Fallback Chains + +Fallback order is enforced by the oRPC inference gateway. If a provider returns an error or exceeds quota, the next provider in the chain is tried. + +### LLM Fallback (Text Generation) + +``` +Production: Vertex AI (Gemini 1.5 Pro) → OpenAI (GPT-4o) → Groq (Llama 3 70B) → HF Dedicated (Mistral 7B) +Staging: Groq (Llama 3 70B) → HF Serverless (Mistral 7B) +Local dev: Ollama (Llama 3 8B) → HF Serverless (Mistral 7B) +``` + +### VLM Fallback (Vision / Multimodal) + +``` +Production: Vertex AI (Gemini 1.5 Pro) → OpenAI (GPT-4o vision) → HF (CLIP + LLM) +``` + +### ASR Fallback (Speech-to-Text) + +``` +Production: OpenAI Whisper API → HF Dedicated (Whisper Large v3) → HF Serverless (Whisper Medium) +Local dev: Ollama (Whisper) → HF Serverless (Whisper Medium) +``` + +### Embedding Fallback + +``` +Production: HF Dedicated (BGE Large) → HF Serverless (MiniLM) +Local dev: Ollama (nomic-embed-text) → HF Serverless (MiniLM) +``` + +### Image Generation Fallback + +``` +Production: Fal (FLUX.1-schnell) → Fal (SDXL) → HF Serverless (SDXL) +``` + +--- + +## Latency Tiers + +| Tier | Target Latency | Use Cases | Providers | +|------|---------------|-----------|-----------| +| **Real-time** | < 500 ms (TTFB) | Streaming chat, live captions, sign-lang overlay | Groq, Gemini Flash (Deno Edge), Claude Haiku (Vercel Edge) | +| **Interactive** | 500 ms – 3 s | UI generation, idea drafts, code suggestions | Gemini 1.5 Pro, GPT-4o, Vertex AI | +| **Batch** | 3 s – 30 s | Market research, compliance reports, long-form | OpenAI, Anthropic, Vertex AI (batch mode) | +| **Async / Background** | > 30 s (queued) | Image generation, full report generation, model fine-tuning | Fal, HF Spaces, GKE batch jobs | + +### Streaming + +All real-time and interactive endpoints support **Server-Sent Events (SSE)** streaming via the Vercel AI SDK `streamText` / `streamObject` helpers, or the `ReadableStream` Deno API: + +```typescript +// Next.js Edge Route (Vercel AI SDK) +import { streamText } from "ai"; +import { openai } from "@ai-sdk/openai"; + +export const runtime = "edge"; + +export async function POST(req: Request) { + const { prompt } = await req.json(); + const result = await streamText({ + model: openai("gpt-4o"), + prompt, + }); + return result.toDataStreamResponse(); +} +``` + +```typescript +// Deno Edge (Gemini Flash via @google/generative-ai) +import { GoogleGenerativeAI } from "npm:@google/generative-ai"; + +const genAI = new GoogleGenerativeAI(Deno.env.get("GOOGLE_AI_API_KEY")!); +const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" }); + +const result = await model.generateContentStream(prompt); +for await (const chunk of result.stream) { + // stream to client +} +``` + +--- + +## vLLM Production Setup (GKE) + +For high-throughput production inference of open-source models: + +```bash +# Deploy vLLM server for Mistral 7B +kubectl apply -f - < Canonical registry of every AI model, SDK binding, deployment path, and containment boundary across the 360 Magicians / MBTQ ecosystem. + +--- + +## Model Registry + +| HuggingFace ID / Model Slug | Type | Source | License | Assigned Platform(s) | +|-----------------------------|------|--------|---------|----------------------| +| `meta-llama/Meta-Llama-3-8B-Instruct` | LLM | HF Hub / Groq / Ollama | Llama 3 Community | mbtq.dev, Quinn AI | +| `meta-llama/Meta-Llama-3-70B-Instruct` | LLM | Groq API | Llama 3 Community | 360magicians hub, agents | +| `mistralai/Mistral-7B-Instruct-v0.3` | LLM | HF Hub / vLLM / Ollama | Apache 2.0 | PinkSync microservices, fallback | +| `mistralai/Mixtral-8x7B-Instruct-v0.1` | LLM | Groq API | Apache 2.0 | Fast inference layer | +| `openai/gpt-4o` | LLM | OpenAI API | Proprietary | Quinn AI, GROW stage | +| `openai/gpt-4` | LLM | OpenAI API | Proprietary | Railway template, mbtq-dev | +| `anthropic/claude-3-5-sonnet` | LLM | Anthropic API | Proprietary | BUILD stage, agent review | +| `anthropic/claude-3-haiku` | LLM | Anthropic API | Proprietary | Fast agent tasks | +| `google/gemini-1.5-pro` | LLM | Vertex AI / AI Studio | Proprietary | 360magicians hub, mbtq.dev | +| `google/gemini-1.5-flash` | LLM | Vertex AI / AI Studio | Proprietary | Gemini CLI bridge, real-time | +| `openai/gpt-4o` (vision) | VLM | OpenAI API | Proprietary | Content generation, media | +| `google/gemini-1.5-pro` (vision) | VLM | Vertex AI | Proprietary | Accessibility AI, sign-lang | +| `openai/whisper-large-v3` | ASR | HF Hub / OpenAI API | MIT | DeafAuth ASL/audio input | +| `openai/whisper-medium` | ASR | HF Hub / Ollama | MIT | PinkSync audio pipeline | +| `openai/clip-vit-large-patch14` | VLM / Embedding | HF Hub | MIT | Sign-language recognition | +| `sentence-transformers/all-MiniLM-L6-v2` | Embedding | HF Hub | Apache 2.0 | Semantic search, RAG | +| `BAAI/bge-large-en-v1.5` | Embedding | HF Hub | MIT | DeafAuth preferences RAG | +| `stabilityai/stable-diffusion-xl-base-1.0` | Image-gen | HF Hub / Fal | CreativeML OpenRAIL-M | Media, Deaf content gen | +| `black-forest-labs/FLUX.1-schnell` | Image-gen | Fal API | Apache 2.0 | Content generation, rapid | +| `codellama/CodeLlama-13b-Instruct-hf` | Code-gen | HF Hub / Ollama | Llama 2 Community | BUILD stage fallback | + +--- + +## Inference Modes + +| Model | API (Hosted) | Local (Ollama/vLLM) | Serverless (Edge/Deno) | Containerized (K8s) | +|-------|:---:|:---:|:---:|:---:| +| Llama 3 8B | Groq | ✓ | — | ✓ | +| Llama 3 70B | Groq | — | — | ✓ | +| Mistral 7B | HF Serverless | ✓ | — | ✓ | +| Mixtral 8x7B | Groq | — | — | — | +| GPT-4o | OpenAI | — | ✓ (via edge proxy) | — | +| GPT-4 | OpenAI | — | — | — | +| Claude 3.5 Sonnet | Anthropic | — | — | — | +| Claude 3 Haiku | Anthropic | — | ✓ (via edge proxy) | — | +| Gemini 1.5 Pro | Vertex AI / AI Studio | — | ✓ (Deno) | — | +| Gemini 1.5 Flash | Vertex AI / AI Studio | — | ✓ (Deno) | — | +| Whisper Large v3 | OpenAI / HF Endpoint | ✓ | — | ✓ | +| CLIP ViT-L/14 | HF Serverless | — | — | ✓ | +| all-MiniLM-L6-v2 | HF Serverless | ✓ | — | ✓ | +| BGE Large | HF Endpoint | — | — | ✓ | +| SDXL | Fal / HF | — | — | ✓ | +| FLUX.1-schnell | Fal | — | — | — | +| CodeLlama 13B | HF Serverless | ✓ | — | ✓ | + +--- + +## AI SDK Bindings + +| SDK | Package | Models / Providers | Layer | +|-----|---------|-------------------|-------| +| **Vercel AI SDK** | `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google` | GPT-4o, Claude, Gemini | Edge + Server (streaming) | +| **Google Generative AI** | `@google/generative-ai` | Gemini 1.5 Pro/Flash | Server, Deno | +| **OpenAI SDK** | `openai` | GPT-4, GPT-4o, Whisper | Server, agent tasks | +| **Anthropic SDK** | `@anthropic-ai/sdk` | Claude 3.5, Claude 3 Haiku | BUILD stage agents | +| **HuggingFace Inference** | `@huggingface/inference` | Llama 3, Mistral, CLIP, Whisper, embeddings | Server, microservices | +| **LangChain** | `langchain` / `@langchain/community` | All (via adapters) | Orchestration, RAG chains | +| **oRPC** | `@orpc/server`, `@orpc/client` | All (RPC wrapper) | Type-safe API layer | +| **Groq SDK** | `groq-sdk` | Llama 3 70B, Mixtral | Fast inference, agents | +| **Fal** | `@fal-ai/client` | SDXL, FLUX.1 | Image/video generation | + +### HuggingFace `@huggingface/inference` — Usage Pattern + +```typescript +import { HfInference } from "@huggingface/inference"; + +const hf = new HfInference(process.env.HF_TOKEN); + +// Text generation (Mistral 7B) +const result = await hf.textGeneration({ + model: "mistralai/Mistral-7B-Instruct-v0.3", + inputs: "[INST] Your prompt here [/INST]", + parameters: { max_new_tokens: 512 }, +}); + +// Feature extraction / embeddings +const embedding = await hf.featureExtraction({ + model: "sentence-transformers/all-MiniLM-L6-v2", + inputs: "Text to embed", +}); + +// Automatic speech recognition +const transcription = await hf.automaticSpeechRecognition({ + model: "openai/whisper-large-v3", + data: audioBlob, +}); +``` + +**Endpoint URL pattern:** `https://api-inference.huggingface.co/models/` +**HF Token scope:** `Read` for public models; `Read` + Inference Endpoints permission for dedicated endpoints. + +### HF Serverless vs. Dedicated Endpoints + +| | HF Serverless Inference | HF Dedicated Endpoint | +|-|------------------------|----------------------| +| **Use when** | Dev, staging, low-traffic | Production, SLA required | +| **Cold start** | Yes (~5–30s) | No (always warm) | +| **Rate limits** | Yes (free tier) | No (dedicated GPU) | +| **Cost** | Free (quota) | Per-hour GPU billing | +| **Auth** | HF_TOKEN | HF_TOKEN + endpoint URL | + +### oRPC — Type-Safe AI Layer + +oRPC wraps all AI provider SDKs into a single type-safe RPC contract: + +```typescript +import { os } from "@orpc/server"; + +export const inferRouter = os.router({ + llm: os + .input(InferLLMSchema) + .handler(async ({ model, prompt, stream }) => { + // route to correct SDK based on model prefix + }), + embed: os + .input(InferEmbedSchema) + .handler(async ({ model, input }) => { ... }), +}); +``` + +--- + +## Per-Platform Model Assignment + +| Platform | Primary Models | Secondary / Fallback | Purpose | +|----------|---------------|----------------------|---------| +| **360magicians.com hub** | Gemini 1.5 Pro, Llama 3 70B | Mistral 7B | Creative AI, content, design | +| **mbtq.dev** | Gemini 1.5 Flash, GPT-4o | Llama 3 8B (Ollama) | Deaf-first dashboard, v0 bridge | +| **PinkSync microservices** | Whisper Large, CLIP, Mistral 7B | all-MiniLM (embeddings) | Accessibility transforms, ASL | +| **DeafAuth** | BGE Large (embeddings), Whisper | Gemini Flash | Identity, preferences, ASR input | +| **Quinn AI** | Claude 3.5 Sonnet, GPT-4o | Llama 3 8B | Dev assistant, BUILD agent | +| **MBTQUniverse** | GPT-4o | Gemini 1.5 Pro | DAO summaries, governance | +| **FibonRose** | Claude 3 Haiku | GPT-4o | Task validation, UI generation | +| **Municipal DAO** | Gemini 1.5 Flash | Mixtral | Real-time governance analysis | +| **Local dev (all)** | Ollama: Llama 3 8B, Mistral 7B | — | No API cost in development | + +--- + +## Capabilities Matrix + +| Model | Text-gen | Vision/VLM | ASL/Sign | ASR | Embedding | Image-gen | Code-gen | +|-------|:--------:|:----------:|:--------:|:---:|:---------:|:---------:|:--------:| +| Llama 3 8B | ✓ | — | — | — | — | — | ✓ | +| Llama 3 70B | ✓ | — | — | — | — | — | ✓ | +| Mistral 7B | ✓ | — | — | — | — | — | ✓ | +| Mixtral 8x7B | ✓ | — | — | — | — | — | ✓ | +| GPT-4o | ✓ | ✓ | ✓ (via vision) | — | — | — | ✓ | +| GPT-4 | ✓ | — | — | — | — | — | ✓ | +| Claude 3.5 Sonnet | ✓ | ✓ | — | — | — | — | ✓ | +| Claude 3 Haiku | ✓ | ✓ | — | — | — | — | ✓ | +| Gemini 1.5 Pro | ✓ | ✓ | ✓ (via vision) | ✓ (native) | — | — | ✓ | +| Gemini 1.5 Flash | ✓ | ✓ | — | ✓ (native) | — | — | ✓ | +| Whisper Large v3 | — | — | — | ✓ | — | — | — | +| Whisper Medium | — | — | — | ✓ | — | — | — | +| CLIP ViT-L/14 | — | ✓ | ✓ | — | ✓ | — | — | +| all-MiniLM-L6-v2 | — | — | — | — | ✓ | — | — | +| BGE Large | — | — | — | — | ✓ | — | — | +| SDXL | — | — | — | — | — | ✓ | — | +| FLUX.1-schnell | — | — | — | — | — | ✓ | — | +| CodeLlama 13B | ✓ | — | — | — | — | — | ✓ | + +--- + +## Deployment Paths + +### Containerized (Docker / Kubernetes) + +Model servers running as dedicated K8s Deployments in GKE (`mbtq.dev` project): + +```yaml +# Example: Ollama model server pod spec +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ollama-llama3 + namespace: inference +spec: + replicas: 2 + selector: + matchLabels: + app: ollama-llama3 + template: + spec: + containers: + - name: ollama + image: gcr.io/mbtq-dev/ollama:llama3-8b + ports: + - containerPort: 11434 + resources: + requests: + nvidia.com/gpu: "1" +``` + +Container image tag strategy: +- `:dev` — local dev build +- `:staging-` — staging deploy +- `:prod-` — production release + +GCR image paths: `gcr.io/mbtq-dev/:` + +### Virtual / Serverless + +| Platform | Models | Notes | +|----------|--------|-------| +| **HF Spaces (Gradio)** | Mistral, Whisper, CLIP | Demo and staging, not SLA-bound | +| **HF Spaces (Streamlit)** | SDXL, FLUX | Visual demos, Deaf media previews | +| **Deno Deploy** | Gemini Flash (via API) | Edge inference proxy, <100ms TTFB | +| **Vercel Edge** | GPT-4o, Claude Haiku (via AI SDK) | Streaming chat, Next.js routes | +| **Railway** | Ollama sidecar container | Dev/staging quick deploys | + +### Local Development + +```yaml +# docker-compose.yml — Ollama sidecar +services: + ollama: + image: ollama/ollama + ports: + - "11434:11434" + volumes: + - ollama_data:/root/.ollama + + app: + environment: + OLLAMA_BASE_URL: http://ollama:11434 + AI_MODEL_OVERRIDE: llama3 # override prod model in local dev +``` + +`.env` model override flags: +``` +AI_MODEL_OVERRIDE=llama3 # use local Ollama instead of OpenAI/Gemini +HF_TOKEN=hf_... # HuggingFace token for serverless inference +OPENAI_API_KEY=sk-... +ANTHROPIC_API_KEY=sk-ant-... +GOOGLE_AI_API_KEY=AIza... +GROQ_API_KEY=gsk_... +FAL_KEY=... +``` + +--- + +## Containment Boundaries + +| Scope | Isolated | Shared Pool | Notes | +|-------|:--------:|:-----------:|-------| +| DeafAuth identity models (BGE, Whisper) | ✓ | — | Dedicated namespace; no cross-service access | +| 360magicians hub (Gemini, Llama 70B) | — | ✓ | Shared inference pool via oRPC gateway | +| PinkSync accessibility transforms (CLIP, Whisper) | ✓ | — | PII: sign-language frames stay in PinkSync namespace | +| Quinn AI assistant (Claude, GPT-4o) | ✓ | — | Agent context isolated per session | +| MBTQUniverse DAO (GPT-4o, Gemini) | — | ✓ | Shared via inference gateway | +| Image generation (SDXL, FLUX) | ✓ | — | GPU workload isolated, rate-limited per user | +| Embeddings (MiniLM, BGE) | — | ✓ | Shared vector service across platforms | + +### Isolation Rules + +1. **PII audio/video** (DeafAuth ASR, PinkSync sign frames) → never leave isolated namespaces. +2. **API keys** → per-service GCP Secret Manager entries; no shared `.env` in production. +3. **Model versions** → pinned in each service's deployment manifest; no `latest` tags in prod. +4. **HF tokens** → scoped to minimum required permissions (`read` only unless endpoint creation needed). + +--- + +## HuggingFace Spaces (Demo / Staging) + +| Space | Model | Purpose | Environment | +|-------|-------|---------|-------------| +| `360magicians/asl-recognizer` | CLIP ViT-L/14 + Whisper | ASL sign demo | Demo/staging | +| `360magicians/deaf-tts-demo` | Bark / SpeechT5 | Text-to-speech Deaf UI | Demo | +| `mbtq-dev/pinksync-a11y` | Mistral 7B + MiniLM | Accessibility transform preview | Staging | +| `mbtq-dev/image-gen-demo` | SDXL / FLUX | Deaf media content generator | Demo | + +> HF Spaces are **not** used for production traffic. Production routes through dedicated HF Endpoints or GKE-hosted model servers. + +--- + +## Related + +- [AI Inference Architecture](./ai-inference.md) +- [Providers, Vendors & Resources](./providers.md) +- [Infrastructure / Ecosystem Architecture](./infrastructure.md) +- [Package Managers & Runtimes](./package-managers.md) +- [OpenAPI Inference Paths](../openapi/openapi.yaml) diff --git a/docs/copilot-bots.md b/docs/copilot-bots.md new file mode 100644 index 0000000..a81c73e --- /dev/null +++ b/docs/copilot-bots.md @@ -0,0 +1,352 @@ +# Copilot, Bots & Auth Access + +> GitHub Copilot suggested prompts, authorized bot/app registrations, and all auth access patterns +> (OAuth, PAT, JWT, GitHub App installation tokens) used across the 360Magicians ecosystem. + +--- + +## GitHub Copilot — Suggested Prompts + +Use these prompts in GitHub Copilot Chat (VS Code, GitHub.com, or Copilot CLI) to get the most +effective assistance across this ecosystem. + +### Codebase Orientation + +``` +@workspace What is the IDEA → BUILD → GROW → MANAGED lifecycle and which agents handle each stage? +@workspace Show me all Magician agent types and their job IDs. +@workspace How does DeafAUTH authentication work across the ecosystem? +@workspace Which projects use pnpm vs npm vs Deno? +@workspace What environment variables does PinkSync need? +``` + +### Code Generation + +``` +# Next.js / TypeScript +Generate a Next.js server action for submitting an idea to POST /idea using DeafAUTH bearer auth. + +Generate a TypeScript hook that connects to the Municipal DAO WebSocket and listens for vote events. + +Create a Zod schema for the BuildRepoRequest matching the openapi/components/schemas/BuildRepoRequest.yaml spec. + +Generate a DeafAUTH SDK registration call with ASL as the preferred language. + +# Accessibility +Add WCAG 2.1 AA compliant visual notification component using shadcn/ui and Tailwind. + +Generate a PinkSync accessibility event POST call for a page_load event with compliance_level gold. +``` + +### PR Review + +``` +@workspace Review this PR for accessibility issues — does it meet Deaf-first design principles? + +@workspace Does this change break any Magician agent job contracts (inputs/outputs)? + +@workspace Check if this PR respects the pnpm-only rule for 360magicians org projects. +``` + +### Debugging + +``` +@workspace Why would a ValidatorMagician review be failing on PR #? + +@workspace How do I fix a WebSocket reconnection issue in Municipal DAO? + +@workspace What's the correct HMAC signature verification for GitHub webhooks? +``` + +### Documentation Generation + +``` +Generate a markdown doc for this new API endpoint following the style of docs/projects/deafauth.md. + +Add JSDoc comments to this server action following the Railway template patterns. + +Create an .env.example file for this new project following the style in docs/environments.md. +``` + +--- + +## Copilot CLI — Suggested Commands + +```bash +# Explain what a file does +gh copilot explain "$(cat docs/git-workflow.md)" + +# Suggest shell commands +gh copilot suggest "deploy pinksync to staging with helm" + +# Translate a natural language request to a command +gh copilot suggest "create a GitHub branch named agent/build-003-frontend" +gh copilot suggest "verify the HMAC signature of an incoming GitHub webhook" +gh copilot suggest "list all open PRs from agent branches in a repo" +``` + +--- + +## Authorized Bots & GitHub Apps + +### 360Magicians Bot (main lifecycle agent) + +| Setting | Value | +|---------|-------| +| App name | `360MagiciansBot` | +| Login | `360MagiciansBot[bot]` | +| Webhook endpoint | `https://api.360magicians.com/webhooks/github` | +| Auth method | GitHub App installation token (JWT → access token) | +| Scopes | Contents R/W, Pull Requests R/W, Issues R/W, Checks R/W, Actions R, Deployments R/W | +| Orgs installed | `360magicians`, `pinkycollie`, `MBTQ-dev`, `PinkSync`, `DeafAUTH` | + +### ValidatorMagician Bot + +| Setting | Value | +|---------|-------| +| App name | `ValidatorMagicianBot` | +| Trigger | PR opened/synchronized | +| Posts | PR review comments, `validation_report.json` | +| Merge permission | Approve + merge when all checks pass | + +### GitHub Copilot (Coding Agent) + +| Setting | Value | +|---------|-------| +| App name | `github-copilot[bot]` | +| Auth | GitHub OAuth (user-authorized) | +| Allowed | Comment on PRs, suggest code, generate docs | +| Not allowed | Merge PRs, push directly to `main` | + +### Dependabot + +| Setting | Value | +|---------|-------| +| Config | `.github/dependabot.yml` | +| Ecosystem | `npm` (root `/`) | +| Schedule | Daily | +| Allowed packages | `@redocly/cli` only (intentionally restricted) | + +--- + +## Auth Access Patterns + +### 1. GitHub App Installation Token (agents → GitHub API) + +Used by all Magician bots. Scoped to a specific installation (org or repo). +Expires after 1 hour — agents refresh as needed. + +```typescript +import { App } from '@octokit/app'; + +const app = new App({ + appId: process.env.GITHUB_APP_ID!, + privateKey: process.env.GITHUB_PRIVATE_KEY!, + webhooks: { secret: process.env.WEBHOOK_SECRET! }, +}); + +// Get an Octokit instance scoped to a specific installation +const octokit = await app.getInstallationOctokit(installationId); + +// Use it +await octokit.rest.pulls.create({ + owner: '360magicians', + repo: 'deaf-gov-platform', + title: 'feat(frontend): scaffold Next.js', + head: 'agent/build-003-frontend', + base: 'develop', +}); +``` + +--- + +### 2. DeafAUTH ****** (humans + agents → lifecycle API) + +All calls to `https://api.360magicians.com` require a DeafAUTH JWT. + +#### Obtain a token + +```bash +# Register (first time) +curl -X POST https://api.deafauth.mbtq.dev/v1/register \ + -H "Content-Type: application/json" \ + -d '{ + "email": "agent@360magicians.com", + "password": "", + "name": "DeveloperMagician" + }' + +# Login +curl -X POST https://api.deafauth.mbtq.dev/v1/login \ + -H "Content-Type: application/json" \ + -d '{ "email": "agent@360magicians.com", "password": "" }' +# → { "token": "eyJ...", "expires_in": 604800 } +``` + +#### Use the token + +```bash +export DEAFAUTH_TOKEN=eyJ... + +curl -H "Authorization: ******" \ + https://api.360magicians.com/jobs/list +``` + +#### Token structure (JWT payload) + +```json +{ + "user_id": "agent-dev-001", + "auth_type": "service_account", + "permissions": ["IDEA_GENERATOR", "BUILD_ACCESS", "GROW_DASHBOARD", "MANAGED_ACCESS"], + "profile": { + "display_name": "DeveloperMagician", + "language": "ASL", + "privacy": "private" + }, + "iat": 1705747200, + "exp": 1706352000 +} +``` + +--- + +### 3. GitHub Personal Access Token (PAT) — human developers only + +PATs are for **human developers only**, not agents. Fine-grained PATs are preferred. + +| Use case | Minimum scopes | +|----------|---------------| +| Clone private repos | `repo:contents (read)` | +| Push to feature branch | `repo:contents (write)` | +| Open PR | `pull_requests (write)` | +| Trigger workflow manually | `actions (write)` | + +```bash +# Store in environment (never hardcode) +export GITHUB_TOKEN=github_pat_... + +# Use with gh CLI +gh auth login --with-token <<< $GITHUB_TOKEN + +# Verify +gh auth status +``` + +**Fine-grained PAT settings:** +- Resource owner: `360magicians` (or the specific org) +- Repository access: only the repos you need +- Expiry: maximum 90 days; rotate at 60 days + +--- + +### 4. Supabase Service Role Key (server-side only) + +Used by mbtq-dev server for privileged database operations. + +```typescript +// server/lib/supabase.ts +import { createClient } from '@supabase/supabase-js'; + +// NEVER expose this key to the browser +const supabaseAdmin = createClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.SUPABASE_SERVICE_ROLE_KEY!, // server only +); +``` + +The anon key (`NEXT_PUBLIC_SUPABASE_ANON_KEY`) is safe to expose in the browser — it is +Row Level Security (RLS) protected. + +--- + +### 5. GCP Service Account (InfraMagician → GCP) + +Used by `InfraMagician` for GKE deployments and GCR image pushes. + +```bash +# Authenticate in CI (GitHub Actions) +- uses: google-github-actions/auth@v2 + with: + credentials_json: ${{ secrets.GCP_SA_KEY }} + +- uses: google-github-actions/setup-gcloud@v2 + +# Push image to GCR +gcloud auth configure-docker gcr.io +docker push gcr.io/mbtq-dev/: + +# Deploy via kubectl +gcloud container clusters get-credentials mbtq-cluster \ + --region us-central1 --project mbtq-dev +``` + +**Service account permissions (least privilege):** + +| Role | Reason | +|------|--------| +| `roles/container.developer` | Deploy to GKE | +| `roles/storage.admin` (scoped to `gcr.io/mbtq-dev`) | Push/pull container images | +| `roles/secretmanager.secretAccessor` | Read secrets at deploy time | + +--- + +### 6. Firebase Service Account (DeafAuth) + +```typescript +// functions/index.ts +import * as admin from 'firebase-admin'; + +admin.initializeApp({ + credential: admin.credential.cert({ + projectId: process.env.FIREBASE_PROJECT_ID, + clientEmail: process.env.FIREBASE_CLIENT_EMAIL, + privateKey: process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n'), + }), +}); +``` + +For local development, use the **Firebase Emulator**: + +```bash +firebase emulators:start --only auth,firestore,functions +# Auth emulator: http://localhost:9099 +# Firestore emulator: http://localhost:8080 +``` + +--- + +## Bot Authorization Checklist + +When onboarding a new bot or GitHub App to the ecosystem: + +- [ ] Register as a GitHub App (not a personal token) +- [ ] Set webhook URL to `https://api.360magicians.com/webhooks/github` +- [ ] Store `WEBHOOK_SECRET` and `GITHUB_PRIVATE_KEY` in GCP Secret Manager +- [ ] Grant minimum required permissions only +- [ ] Install on specific repos/orgs (not "all repositories" unless required) +- [ ] Add bot login (`BotName[bot]`) to the `CODEOWNERS` exception list if it needs to push to protected branches +- [ ] Register the bot's DeafAUTH service account with the `service_account` auth type +- [ ] Document the bot in this file under **Authorized Bots & GitHub Apps** +- [ ] Add webhook subscription to `api.360magicians.com/webhooks/subscribe` if it needs job events + +--- + +## Protected Branch Push Access for Bots + +Bots that need to push to `develop` (e.g. `DeveloperMagician`) require a branch protection bypass rule: + +**GitHub → Settings → Branches → develop → Edit → Allow specified actors to bypass required pull requests** + +Add: `360MagiciansBot[bot]` + +> Bots **must never** bypass protection on `main`. All `main` merges must go through a PR with at least one human review. + +--- + +## Related + +- [Triggers, Webhooks & Prompts](./triggers-webhooks.md) +- [Pipeline Handoffs](./pipeline-handoffs.md) +- [Environments & Bootstrap](./environments.md) +- [Git Workflow](./git-workflow.md) diff --git a/docs/environments.md b/docs/environments.md new file mode 100644 index 0000000..388d8ed --- /dev/null +++ b/docs/environments.md @@ -0,0 +1,246 @@ +# Environments: Dev → Staging → Production + +> Environment separation, bootstrap steps, and per-project environment variable reference for the 360Magicians MBTQ ecosystem. + +--- + +## Environment Tiers + +| Tier | Purpose | URL pattern | Deployed by | +|------|---------|-------------|------------| +| **dev** | Local development | `localhost` | Developer / agent on local machine | +| **staging** | Integration & QA | `*.staging.mbtq.dev` | CI after merge to `develop` | +| **prod** | Live production | `*.mbtq.dev`, `*.360magicians.com` | CI after merge to `main` | + +--- + +## Bootstrap (First-Time Setup) + +### Prerequisites + +| Tool | Min version | Install | +|------|------------|---------| +| Node.js | 20 LTS | [nodejs.org](https://nodejs.org) | +| pnpm | 9.x | `npm i -g pnpm` | +| Deno | 1.x | [deno.land](https://deno.land) | +| Docker | 24.x | [docker.com](https://docker.com) | +| `kubectl` | 1.29 | [kubernetes.io](https://kubernetes.io/docs/tasks/tools/) | +| Helm | 3.x | [helm.sh](https://helm.sh) | +| GCP CLI (`gcloud`) | Latest | [cloud.google.com/sdk](https://cloud.google.com/sdk) | + +### Local Bootstrap (dev) + +```bash +# 1. Authenticate with GCP (for Secret Manager / GCR access) +gcloud auth login +gcloud config set project mbtq-dev + +# 2. Clone the repo you want to work on (example: fibonrose) +git clone https://github.com/360magicians/fibonrose +cd fibonrose +git checkout develop + +# 3. Copy the dev env template and fill in values +cp .env.example .env.local + +# 4. Install dependencies (see Package Managers doc for which tool per project) +pnpm install # fibonrose, pinksync, railway-template +# OR +npm install # municipal-dao, mbtq-dev client+server + +# 5. Start the dev server +pnpm dev # or npm run dev +``` + +### Staging Bootstrap (CI) + +Staging is deployed automatically from the `develop` branch by GitHub Actions. +The workflow: +1. Runs lint + type-check + tests +2. Builds Docker image → pushes to `gcr.io/mbtq-dev/:staging-` +3. Runs `make deploy-all ENV=staging IMAGE_TAG=staging-` +4. Posts the staging URL as a PR/commit status + +### Production Bootstrap (CI) + +Production is deployed from `main` only: +1. Same lint/test/build steps +2. Image tagged as `gcr.io/mbtq-dev/:` +3. Runs `make deploy-all ENV=prod IMAGE_TAG=` +4. `OpsMagician` updates the monitoring dashboard URL (`managed-003`) + +--- + +## Environment Variables — Per Project + +> All secrets must be stored in **GCP Secret Manager** for staging and prod. +> For dev, use `.env.local` (gitignored). **Never commit `.env` files.** + +### FibonRose + +```env +# .env.local (dev only) +NEXT_PUBLIC_API_URL=http://localhost:3000/api +NEXT_PUBLIC_DEAFAUTH_URL=http://localhost:4000 +``` + +```env +# staging / prod (GCP Secret Manager keys) +NEXT_PUBLIC_API_URL=https://api.360magicians.com +NEXT_PUBLIC_DEAFAUTH_URL=https://deafauth.mbtq.dev +``` + +--- + +### PinkSync + +```env +# All environments — values differ per tier +DEAFAUTH_API_URL=https://deafauth.mbtq.dev # or localhost:4000 in dev +VERTEX_AI_ENDPOINT=https://api.360magicians.com # or mock in dev +OFFLINE_SYNC_ENABLED=true +ACCESSIBILITY_TRANSFORMS=visual,tactile,sign-language,high-contrast + +# Staging / prod only +GOOGLE_APPLICATION_CREDENTIALS=/var/secrets/gcp-sa.json +``` + +--- + +### mbtq.dev (client + server) + +```env +# Client (NEXT_PUBLIC_ vars are bundled into the frontend) +NEXT_PUBLIC_SUPABASE_URL=https://.supabase.co +NEXT_PUBLIC_SUPABASE_ANON_KEY= +NEXT_PUBLIC_WS_URL=ws://localhost:8080 # dev +# NEXT_PUBLIC_WS_URL=wss://mbtq.dev/ws # prod + +# Server +DATABASE_URL=******localhost:5432/mbtq_dev +SUPABASE_SERVICE_ROLE_KEY= +OPENAI_API_KEY= +ANTHROPIC_API_KEY= + +# WebSocket server +WS_PORT=8080 +WS_HOST=0.0.0.0 +``` + +--- + +### Municipal DAO + +```env +# WebSocket server +WS_PORT=8080 +WS_HOST=localhost # dev +# WS_HOST=0.0.0.0 # prod + +NEXT_PUBLIC_WS_URL=ws://localhost:8080 # dev +# NEXT_PUBLIC_WS_URL=wss://your-domain.com/ws # prod + +# Auth +DEAFAUTH_TOKEN_SECRET= +``` + +--- + +### DeafAuth + +```env +# Firebase config (dev: use Firebase emulator) +FIREBASE_PROJECT_ID=mbtq-dev +FIREBASE_CLIENT_EMAIL= +FIREBASE_PRIVATE_KEY= + +# JWT +JWT_SECRET= +JWT_EXPIRY=7d + +# API +DEAFAUTH_API_URL=https://api.deafauth.mbtq.dev +PORT=4000 +``` + +--- + +### Railway Template + +```env +# Auth (uses mock values in dev — demo user is built in) +DATABASE_URL=******localhost:5432/railway_dev + +# App +NODE_ENV=development # or production +PORT=3000 +HOSTNAME=0.0.0.0 # required for Railway container networking + +# Optional: email verification +SMTP_HOST=localhost +SMTP_PORT=1025 +``` + +--- + +### MBTQUniverse + +```env +NODE_ENV=development +PORT=3001 + +# DAO config +DAO_QUORUM_THRESHOLD=0.51 +STAKING_REWARD_RATE=0.05 + +# Future: blockchain RPC +# RPC_URL=https://mainnet.infura.io/v3/ +``` + +--- + +## Secrets Management + +| Tier | Method | +|------|--------| +| dev | `.env.local` (gitignored, never committed) | +| staging | GCP Secret Manager, mounted via CSI driver | +| prod | GCP Secret Manager, mounted via CSI driver | + +**Rule:** any key suffixed with `_KEY`, `_SECRET`, `_TOKEN`, `_PASSWORD`, or `_PRIVATE_KEY` must +always come from Secret Manager in non-dev environments. + +### Adding a new secret + +```bash +# Add to GCP Secret Manager +echo -n "my-secret-value" | gcloud secrets create MY_SECRET_NAME \ + --data-file=- --project=mbtq-dev + +# Grant the Kubernetes service account access +gcloud secrets add-iam-policy-binding MY_SECRET_NAME \ + --member="serviceAccount:@mbtq-dev.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" +``` + +--- + +## Environment Promotion Checklist + +Before promoting from staging → prod: + +- [ ] All CI checks pass on `main` +- [ ] Staging smoke tests pass +- [ ] Helm diff reviewed (`make diff- ENV=prod`) +- [ ] Secrets updated in GCP Secret Manager (prod) +- [ ] `OpsMagician` monitoring dashboard shows healthy metrics +- [ ] Rollback plan confirmed (`make rollback- ENV=prod`) + +--- + +## Related + +- [Helm Deployment](./helm.md) +- [Git Workflow](./git-workflow.md) +- [Providers, Vendors & Resources](./providers.md) +- [Package Managers & Runtimes](./package-managers.md) diff --git a/docs/git-workflow.md b/docs/git-workflow.md new file mode 100644 index 0000000..f10df13 --- /dev/null +++ b/docs/git-workflow.md @@ -0,0 +1,200 @@ +# Git Workflow & GitHub Integration + +> How agents and humans interact with git, GitHub branches, the GitHub Graph API, and CI/CD events. + +--- + +## Branch Strategy + +The 360Magicians ecosystem uses a **lifecycle-aligned branching model**. + +| Branch | Purpose | Who creates it | +|--------|---------|----------------| +| `main` | Production-ready code | Protected — merged via PR only | +| `develop` | Integration branch | Humans + agents merge feature branches here | +| `agent/` | Work created by a Magician agent | `DeveloperMagician` automatically | +| `feature/` | Human-driven feature work | Developer | +| `ux/ui` | UI/UX iteration branch | Designer (e.g. FibonRose `ux/ui`) | +| `fix/` | Bug fixes | Developer or `OpsMagician` | +| `release/` | Release preparation | `InfraMagician` | + +### Naming Conventions + +``` +agent/build-003-frontend-codebase +feature/deaf-auth-wallet-login +fix/websocket-reconnect-timeout +release/1.2.0 +ux/ui +``` + +--- + +## Agent Git Flow + +When `DeveloperMagician` receives a `build-001` job (create repo), it: + +1. Calls `POST /build/repo` → GitHub API `POST /orgs/{org}/repos` +2. Initialises the repo with a `main` branch and README +3. Creates a `develop` branch from `main` +4. Opens a tracking issue with the full job spec (`job_id`, `inputs`, `outputs`) +5. Subsequent build jobs (`build-003`, `build-004`) branch from `develop` as `agent/` +6. On job completion the agent opens a PR: `agent/` → `develop` +7. `ValidatorMagician` reviews the PR and posts a review comment with `validation_report.json` +8. On approval, the PR is merged and the branch deleted + +``` +main + └── develop + ├── agent/build-003-frontend ← DeveloperMagician + ├── agent/build-004-backend ← DeveloperMagician + └── feature/dashboard-ui ← human +``` + +--- + +## GitHub Graph API + +The GitHub **GraphQL API** (`api.github.com/graphql`) is used by agents to: + +- Query repository status and open PRs +- Retrieve commit history for a job branch +- Check CI check-run statuses before merging +- List review comments from `ValidatorMagician` + +### Example: check PR status + +```graphql +query CheckPR($owner: String!, $repo: String!, $number: Int!) { + repository(owner: $owner, name: $repo) { + pullRequest(number: $number) { + state + mergeable + reviewDecision + commits(last: 1) { + nodes { + commit { + statusCheckRollup { + state + } + } + } + } + } + } +} +``` + +### Example: list agent branches + +```graphql +query AgentBranches($owner: String!, $repo: String!) { + repository(owner: $owner, name: $repo) { + refs(refPrefix: "refs/heads/agent/", first: 20) { + nodes { + name + target { + ... on Commit { authoredDate } + } + } + } + } +} +``` + +--- + +## GitHub Events & Webhooks + +Agents subscribe to GitHub webhook events to trigger lifecycle actions: + +| Event | Payload | Agent Action | +|-------|---------|-------------| +| `push` (to `develop`) | Branch, commits | `ValidatorMagician` runs lint/test | +| `pull_request.opened` | PR number, branch | `ValidatorMagician` starts review | +| `pull_request_review.submitted` | Review state | `DeveloperMagician` checks approval | +| `check_run.completed` | Status, conclusion | `InfraMagician` triggers deploy if passing | +| `release.published` | Tag, release URL | `OpsMagician` updates monitoring dashboard | +| `issues.opened` | Title, body | `IdeaMagician` parses idea prompt if labelled `idea` | + +### Webhook Payload Example (push) + +```json +{ + "ref": "refs/heads/agent/build-003-frontend", + "after": "abc1234", + "repository": { "full_name": "360magicians/deaf-gov-platform" }, + "pusher": { "name": "DeveloperMagician[bot]" }, + "commits": [ + { + "message": "feat(frontend): scaffold Next.js app router", + "added": ["src/app/page.tsx"], + "modified": [] + } + ] +} +``` + +--- + +## CI/CD Pipeline + +Each repository runs GitHub Actions: + +``` +push / PR → lint → type-check → test → build → (on main) deploy +``` + +### Standard Workflow Steps + +| Step | Tool | Target | Output | +|------|------|--------|--------| +| Lint | ESLint / oxlint | `src/**` | Pass / fail with annotations | +| Type check | `tsc --noEmit` | `tsconfig.json` | Type errors | +| Unit tests | Vitest / Jest | `**/*.test.ts` | Coverage report | +| Build | Next.js / Vite | `src/` | `.next/` or `dist/` | +| Docker build | Docker / Buildx | `Dockerfile` | OCI image pushed to GCR | +| Deploy | Helm / Railway | Helm values or Railway project | Staging / production URL | + +### Branch Protection Rules (recommended) + +``` +main: + required_status_checks: [lint, type-check, test, build] + required_reviews: 1 + dismiss_stale_reviews: true + enforce_admins: false + +develop: + required_status_checks: [lint, type-check] + required_reviews: 0 +``` + +--- + +## Job Dependency Graph (DAG) + +The `depends_on` field in the Job schema forms a directed acyclic graph (DAG) that maps directly to git branch sequencing: + +``` +idea-001 (IdeaMagician) + └── idea-002 (ValidatorMagician) + └── idea-003 (ResearchMagician) + └── build-001 (DeveloperMagician — creates repo & develop branch) + ├── build-002 (DesignMagician — wireframes on agent/build-002) + │ └── build-003 (DeveloperMagician — frontend on agent/build-003) + └── build-004 (DeveloperMagician — backend on agent/build-004) + └── build-005 (InfraMagician — deploys staging) + └── grow-001 / grow-002 / grow-003 … +``` + +Each node is a git branch; each edge is a `depends_on` constraint enforced before the next branch is created. + +--- + +## Related + +- [Infrastructure / Ecosystem Architecture](./infrastructure.md) +- [Helm Deployment](./helm.md) +- [Environments (dev → prod)](./environments.md) +- [DeafAuth — Lifecycle Job API](./projects/deafauth.md) diff --git a/docs/helm.md b/docs/helm.md new file mode 100644 index 0000000..e49a766 --- /dev/null +++ b/docs/helm.md @@ -0,0 +1,292 @@ +# Helm Deployment + +> Kubernetes deployment via Helm for the 360Magicians MBTQ ecosystem services on GCP (project: `mbtq.dev`). + +--- + +## Overview + +All long-running services in the MBTQ ecosystem are deployed to Kubernetes (GKE) using **Helm charts**. +`InfraMagician` is the agent responsible for `helm upgrade --install` calls during the BUILD and MANAGED lifecycle stages. + +--- + +## Chart Layout + +``` +helm/ +├── charts/ +│ ├── 360magicians/ # Vertex AI Multi-Domain Hub +│ ├── pinksync/ # Accessibility AI Middleware +│ ├── mbtq-platform/ # Deaf-First Platform (mbtq.dev) +│ ├── deafauth/ # Universal Identity Layer +│ └── mbtquniverse/ # DAO + Web3 + Staking +├── environments/ +│ ├── dev/ +│ │ └── values.yaml # Development overrides +│ ├── staging/ +│ │ └── values.yaml # Staging overrides +│ └── prod/ +│ └── values.yaml # Production values +└── Makefile # Deployment targets +``` + +--- + +## Services & Chart Values + +### 360magicians (Vertex AI Hub) + +```yaml +# Default values +image: + repository: gcr.io/mbtq-dev/360magicians-vertex-ai + tag: latest + pullPolicy: Always + +replicaCount: 5 + +service: + port: 8080 + +env: + VERTEX_AI_PROJECT: mbtq.dev + VERTEX_AI_LOCATION: us-central1 + ACCESSIBILITY_FIRST: "true" + +ingress: + hosts: + - creative-ai.360magicians.com + - design-ai.360magicians.com + - content-ai.360magicians.com + - accessibility-ai.360magicians.com +``` + +### pinksync (Accessibility Middleware) + +```yaml +image: + repository: gcr.io/mbtq-dev/pinksync-accessibility + tag: latest + +replicaCount: 3 + +service: + port: 8081 + +env: + DEAFAUTH_API_URL: https://deafauth.mbtq.dev + VERTEX_AI_ENDPOINT: https://api.360magicians.com + OFFLINE_SYNC_ENABLED: "true" + ACCESSIBILITY_TRANSFORMS: visual,tactile,sign-language,high-contrast +``` + +### mbtq-platform (Deaf-First Platform) + +```yaml +image: + repository: gcr.io/mbtq-dev/mbtq-platform + tag: latest + +replicaCount: 4 + +service: + port: 3000 + +env: + NEXT_PUBLIC_WS_URL: wss://mbtq.dev/ws + DEAFAUTH_API_URL: https://deafauth.mbtq.dev +``` + +### deafauth (Identity Layer) + +```yaml +image: + repository: gcr.io/mbtq-dev/deafauth + tag: latest + +replicaCount: 3 + +service: + port: 4000 + +env: + JWT_SECRET: + FIREBASE_PROJECT_ID: mbtq-dev +``` + +### mbtquniverse (DAO + Web3) + +```yaml +image: + repository: gcr.io/mbtq-dev/mbtquniverse + tag: latest + +replicaCount: 2 + +service: + port: 3001 + +env: + DAO_QUORUM_THRESHOLD: "0.51" + STAKING_REWARD_RATE: "0.05" +``` + +--- + +## Environment Overrides + +### dev `environments/dev/values.yaml` + +```yaml +replicaCount: 1 # Single replica to save cost +image: + tag: dev-latest +env: + LOG_LEVEL: debug + MOCK_AI: "true" # Use mock AI responses in dev +resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 500m + memory: 512Mi +``` + +### staging `environments/staging/values.yaml` + +```yaml +replicaCount: 2 +image: + tag: staging-latest +env: + LOG_LEVEL: info +resources: + requests: + cpu: 250m + memory: 256Mi + limits: + cpu: 1000m + memory: 1Gi +``` + +### prod `environments/prod/values.yaml` + +```yaml +replicaCount: 5 # Full HA replica count +image: + tag: "" # Set by CI via --set image.tag=$GIT_SHA +env: + LOG_LEVEL: warn +autoscaling: + enabled: true + minReplicas: 3 + maxReplicas: 10 + targetCPUUtilizationPercentage: 70 +podDisruptionBudget: + minAvailable: 2 +resources: + requests: + cpu: 500m + memory: 512Mi + limits: + cpu: 2000m + memory: 2Gi +``` + +--- + +## Deployment Targets (Makefile) + +```makefile +ENV ?= dev + +# Deploy a single service +deploy-%: + helm upgrade --install $* ./helm/charts/$* \ + -f ./helm/environments/$(ENV)/values.yaml \ + --namespace $(ENV) \ + --create-namespace \ + --set image.tag=$(IMAGE_TAG) + +# Deploy all services +deploy-all: + $(MAKE) deploy-360magicians ENV=$(ENV) + $(MAKE) deploy-pinksync ENV=$(ENV) + $(MAKE) deploy-mbtq-platform ENV=$(ENV) + $(MAKE) deploy-deafauth ENV=$(ENV) + $(MAKE) deploy-mbtquniverse ENV=$(ENV) + +# Rollback a service +rollback-%: + helm rollback $* 0 --namespace $(ENV) + +# Show diff before upgrading +diff-%: + helm diff upgrade $* ./helm/charts/$* \ + -f ./helm/environments/$(ENV)/values.yaml + +# Render templates without deploying +template-%: + helm template $* ./helm/charts/$* \ + -f ./helm/environments/$(ENV)/values.yaml +``` + +### Usage + +```bash +# Deploy pinksync to dev +make deploy-pinksync ENV=dev IMAGE_TAG=dev-latest + +# Deploy all services to staging +make deploy-all ENV=staging IMAGE_TAG=abc1234 + +# Deploy to prod (CI sets IMAGE_TAG automatically) +make deploy-all ENV=prod IMAGE_TAG=$GIT_SHA +``` + +--- + +## InfraMagician Job (`build-005`) + +| Field | Value | +|-------|-------| +| Job ID | `build-005` | +| Agent | `InfraMagician` | +| Inputs | `frontend_codebase.zip`, `backend_codebase.zip`, `tech_stack` | +| Output | `staging_url` | +| `depends_on` | `["build-003", "build-004"]` | + +Steps performed: +1. Build Docker image from codebase zip +2. Push to `gcr.io/mbtq-dev/:` +3. Run `helm upgrade --install` with staging values +4. Wait for rollout: `kubectl rollout status deployment/` +5. Run smoke test against `staging_url` +6. Return `staging_url` as job output + +--- + +## Secrets Management + +Sensitive values are **never stored in Helm values files**. All secrets are pulled from +**GCP Secret Manager** at pod startup via the [Secret Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/): + +```yaml +volumes: + - name: secrets + csi: + driver: secrets-store.csi.k8s.io + readOnly: true + volumeAttributes: + secretProviderClass: mbtq-secrets +``` + +--- + +## Related + +- [Infrastructure / Ecosystem Architecture](./infrastructure.md) +- [Git Workflow](./git-workflow.md) +- [Environments (dev → prod)](./environments.md) diff --git a/docs/infrastructure.md b/docs/infrastructure.md new file mode 100644 index 0000000..7f00a55 --- /dev/null +++ b/docs/infrastructure.md @@ -0,0 +1,109 @@ +# MBTQ Deaf-First AI Ecosystem Architecture + +Source: [`360magicians/municipal-dao`](https://github.com/360magicians/municipal-dao) — `ecosystem-architecture/mbtq-ecosystem.yaml` + +--- + +## Platform Overview + +The ecosystem runs on **GCP project: mbtq.dev** and consists of five interconnected platforms: + +| Platform | Domain | Role | +|----------|--------|------| +| **360magicians.com** | Vertex AI Multi-Domain Hub | Creative, design, content, and accessibility AI endpoints | +| **pinksync.io** | Accessibility AI Middleware | AI transformation, offline sync, cross-platform delivery | +| **mbtq.dev** | Deaf-First Platform | v0 Studio + Gemini CLI integration, Deaf-first UI dashboard | +| **mbtquniverse.com** | DAO + Web3 + Staking | On-chain governance, staking, community treasury | +| **DeafAUTH** | Universal Identity Layer | Cross-ecosystem auth, accessibility preferences, AI personalization | + +--- + +## Service Map + +### 360magicians.com — Vertex AI Multi-Domain Hub + +Endpoints: +- `creative-ai.360magicians.com` +- `design-ai.360magicians.com` +- `content-ai.360magicians.com` +- `accessibility-ai.360magicians.com` + +Kubernetes: 5 replicas · `gcr.io/mbtq-dev/360magicians-vertex-ai:latest` · port 8080 +Environment: `VERTEX_AI_PROJECT=mbtq.dev`, `VERTEX_AI_LOCATION=us-central1`, `ACCESSIBILITY_FIRST=true` + +--- + +### pinksync.io — Accessibility AI Middleware + +Services: +- `ai-transformation` +- `accessibility-layer` +- `data-synchronization` +- `offline-sync` +- `cross-platform-delivery` + +Kubernetes: 3 replicas · `gcr.io/mbtq-dev/pinksync-accessibility:latest` · port 8081 +Accessibility transforms: `visual, tactile, sign-language, high-contrast` + +--- + +### mbtq.dev — Deaf-First Platform + +Services: +- `v0-studio-integration` +- `gemini-cli-bridge` +- `deaf-first-ui-dashboard` +- `ai-google-studio-proxy` + +Kubernetes: 4 replicas · `gcr.io/mbtq-dev/mbtq-platform:latest` · port 3000 + +--- + +### DeafAUTH — Universal Identity Layer + +Services: +- `cross-ecosystem-auth` +- `accessibility-preferences` +- `ai-personalization` +- `community-verification` + +See also: [DeafAuth Project Docs](./projects/deafauth.md) + +--- + +## API Reference + +Base URL: `https://api.360magicians.com` + +Authentication via DeafAUTH bearer token: + +```bash +export DEAFAUTH_TOKEN= +curl -H "Authorization: ******" \ + https://api.360magicians.com/jobs/list +``` + +User profile example: + +```json +{ + "user_id": "deaf123", + "auth_type": "web3_wallet", + "permissions": ["IDEA_GENERATOR", "BUILD_ACCESS", "GROW_DASHBOARD"], + "profile": { + "display_name": "PinkMagician", + "language": "ASL", + "privacy": "private" + } +} +``` + +--- + +## References + +- [DeafAUTH Docs](https://deafauth.mbtq.dev/docs) +- [360Magicians API](https://api.360magicians.com/docs) +- [LifecycleBlueprint JSON Schema](https://docs.mbtq.dev/lifecycleblueprint) +- [AI Model Manifest](./ai-model-manifest.md) +- [AI Inference Architecture](./ai-inference.md) diff --git a/docs/package-managers.md b/docs/package-managers.md new file mode 100644 index 0000000..dafa98c --- /dev/null +++ b/docs/package-managers.md @@ -0,0 +1,316 @@ +# Package Managers & Runtimes + +> Which runtime and package manager each project uses, why, and how to run dev/build/test across the ecosystem. + +--- + +## Quick Reference + +| Project | Runtime | Package Manager | Server Pattern | Framework | +|---------|---------|----------------|----------------|-----------| +| **FibonRose** | Node.js 20 | `pnpm` | Next.js App Router | Next.js 15 | +| **PinkSync (360magicians)** | Node.js 20 | `pnpm` | Next.js App Router | Next.js 15 | +| **PinkSync microservices** | Deno 1.x | native (import maps) | Deno HTTP | Fresh | +| **Railway Template** | Node.js 20 | `npm` | Next.js App Router + `/api/health` | Next.js 15 | +| **Municipal DAO** | Node.js 20 | `npm` | WebSocket + Next.js | Next.js 15 | +| **mbtq-dev client** | Node.js 20 | `npm` | Vite SPA | React 18 + Vite | +| **mbtq-dev server** | Node.js 20 | `npm` | Express REST API | TypeScript + Prisma | +| **MBTQUniverse** | Node.js 20 | `npm` | Express API gateway | Vanilla JS / ESM | +| **DeafAuth (360magicians)** | Node.js 20 | `pnpm` | Next.js App Router | Next.js 15 + Firebase | +| **DeafAUTH SDK (MBTQ-dev)** | Node.js 20 | `npm` | Framework-agnostic library | TypeScript | +| **Auto-API (MBTQ-dev)** | Python 3.11 | `pip` | FastAPI | FastAPI | +| **pinksync-starter (MBTQ-dev)** | Python 3.11 | `pip` | FastAPI / Flask | Python | + +--- + +## pnpm Projects + +**Used by:** FibonRose, PinkSync (360magicians org), DeafAuth (360magicians org) + +pnpm is preferred for Next.js/TypeScript projects in the 360magicians org because it: +- Uses hard links for a shared content-addressable store (faster installs, less disk) +- Enforces strict dependency hoisting (avoids phantom dependencies) +- Has first-class monorepo support via workspaces + +### Common Commands + +```bash +# Install +pnpm install + +# Dev server +pnpm dev + +# Production build +pnpm build + +# Start built server +pnpm start + +# Lint +pnpm lint + +# Type check +pnpm type-check +``` + +### FibonRose — Getting Started + +```bash +git clone https://github.com/360magicians/fibonrose +cd fibonrose +git checkout ux/ui +pnpm install +cp .env.example .env.local # fill in NEXT_PUBLIC_* vars +pnpm dev +# → http://localhost:3000 +``` + +--- + +## npm Projects + +**Used by:** Railway Template, Municipal DAO, mbtq-dev, MBTQUniverse, DeafAUTH SDK + +npm is used in projects where Railway auto-detection, simplicity, or contributor accessibility is the priority. + +### Railway Template — Getting Started + +```bash +git clone https://github.com/360magicians/railway_nextjs_with_shadcn +cd railway_nextjs_with_shadcn +npm install +cp .env.example .env.local +npm run dev +# → http://localhost:3000 +# Demo: demo@example.com / password123 +``` + +### Municipal DAO — Getting Started + +```bash +git clone https://github.com/360magicians/municipal-dao +cd municipal-dao +npm install + +# Terminal 1 — WebSocket server +npm run ws-server # → ws://localhost:8080 + +# Terminal 2 — Next.js app +npm run dev # → http://localhost:3000 +``` + +### mbtq-dev — Getting Started (client + server) + +```bash +git clone https://github.com/pinkycollie/mbtq-dev +cd mbtq-dev + +# Client (React + Vite) +cd client +npm install +npm run dev # → http://localhost:5173 + +# Server (Express + Prisma) +cd ../server +npm install +npx prisma migrate dev +npm run dev # → http://localhost:4000 +``` + +#### Server Structure (`/server`) + +``` +server/ +├── routes/ +│ ├── auth.ts # DeafAUTH integration routes +│ ├── ideas.ts # IDEA lifecycle endpoints +│ ├── builds.ts # BUILD lifecycle endpoints +│ └── content.ts # Content fulfillment API +├── models/ +│ └── schema.prisma # Prisma ORM schema +├── hooks/ # Business logic (service layer) +│ ├── useIdea.ts +│ ├── useBuild.ts +│ └── useContent.ts +├── middleware/ +│ ├── auth.ts # DeafAUTH JWT validation +│ └── accessibility.ts # Accessibility headers +└── index.ts # Express entry point (PORT=4000) +``` + +#### Server API Targets & Outputs + +| Route | Method | Input | Output | +|-------|--------|-------|--------| +| `/api/health` | GET | — | `{ status: "ok" }` | +| `/api/ideas` | POST | `{ prompt }` | `idea.json` | +| `/api/builds` | POST | `{ idea_id, tech_stack }` | `{ job_id, branch_url }` | +| `/api/content` | POST | `{ creator_id, request }` | `{ fulfillment_id }` | +| `/api/auth/login` | POST | `{ email, password }` | DeafAUTH JWT | + +--- + +## Deno Projects + +**Used by:** PinkSync microservices (`PinkSync/PinkSync`) + +Deno provides: +- Native TypeScript execution (no build step) +- Secure by default (explicit permissions) +- Built-in test runner and formatter +- URL-based imports (no `node_modules`) + +### PinkSync Deno Services + +```bash +# No install step — Deno fetches deps on first run + +# Run event-orchestrator +deno run --allow-net --allow-env services/event-orchestrator/main.ts + +# Run asl-glosser +deno run --allow-net --allow-read services/asl-glosser/main.ts + +# Run tests +deno test --allow-net services/ + +# Format +deno fmt + +# Lint +deno lint +``` + +### Import Map (Deno) + +```json +{ + "imports": { + "std/": "https://deno.land/std@0.208.0/", + "oak": "https://deno.land/x/oak@v12.6.1/mod.ts", + "djwt/": "https://deno.land/x/djwt@v3.0.2/" + } +} +``` + +--- + +## Deno Fresh + +**Used by:** PinkSync API broker (lightweight routes) + +[Fresh](https://fresh.deno.dev) is a Deno-native full-stack web framework with: +- Islands architecture (minimal JS to browser) +- File-based routing +- Zero build step +- No virtual DOM + +### Fresh Getting Started + +```bash +# Requires Deno installed +deno run -A -r https://fresh.deno.dev pinksync-fresh +cd pinksync-fresh +deno task start # → http://localhost:8000 +``` + +### Fresh Project Layout + +``` +pinksync-fresh/ +├── routes/ +│ ├── index.tsx # Home page (server-rendered) +│ ├── v1/ +│ │ ├── events.ts # POST /v1/events +│ │ ├── capabilities.ts +│ │ └── subscribe.ts +├── islands/ +│ └── AccessibilityWidget.tsx # Client-interactive component +├── static/ +│ └── styles.css +└── deno.json +``` + +--- + +## Python Projects + +**Used by:** Auto-API (`MBTQ-dev/Auto-API`), pinksync-starter (`MBTQ-dev/pinksync-starter`, `PinkSync/Core-principles`) + +```bash +# Bootstrap +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r requirements.txt + +# Run FastAPI dev server +uvicorn main:app --reload --port 8000 +``` + +--- + +## HTML / Static + +**Used by:** PinkSync browser extension, landing pages, `public/` directories + +The PinkSync browser extension is built as plain HTML + vanilla JS (no bundler): + +``` +browser-extension/ +├── manifest.json +├── popup.html # Extension popup UI +├── popup.js # Vanilla JS — no framework +├── content.js # Injected content script +└── icons/ +``` + +Build (pack for Chrome Web Store): +```bash +cd browser-extension +zip -r extension.zip . -x "*.DS_Store" +``` + +--- + +## AI SDKs & Inference Clients + +| Package | Classification | Runtime | Projects | +|---------|---------------|---------|---------| +| **`ai` (Vercel AI SDK)** | Open Source (Apache 2.0) | Node.js / Edge | Next.js projects, streaming chat routes | +| **`@ai-sdk/openai`** | Open Source (Apache 2.0) | Node.js / Edge | GPT-4, GPT-4o (AI SDK provider) | +| **`@ai-sdk/anthropic`** | Open Source (Apache 2.0) | Node.js / Edge | Claude (AI SDK provider) | +| **`@ai-sdk/google`** | Open Source (Apache 2.0) | Node.js / Edge | Gemini (AI SDK provider) | +| **`@google/generative-ai`** | Open Source (Apache 2.0) | Node.js / Deno | Gemini direct SDK | +| **`openai`** | Open Source (Apache 2.0) | Node.js | OpenAI + vLLM-compatible endpoints | +| **`@anthropic-ai/sdk`** | Open Source (MIT) | Node.js | Claude SDK — BUILD stage agents | +| **`@huggingface/inference`** | Open Source (Apache 2.0) | Node.js / Deno | HF Hub models (Llama 3, Mistral, CLIP, Whisper) | +| **`groq-sdk`** | Open Source (Apache 2.0) | Node.js | Groq LPU fast inference | +| **`@fal-ai/client`** | Open Source (MIT) | Node.js / Deno | Image/video generation (SDXL, FLUX.1) | +| **`langchain`** | Open Source (MIT) | Node.js | Orchestration, RAG chains | +| **`@orpc/server`** | Open Source (MIT) | Node.js / Deno | Type-safe RPC server wrapping all AI SDKs | +| **`@orpc/client`** | Open Source (MIT) | Node.js / Browser | Type-safe RPC client | + +See [AI Model Manifest](./ai-model-manifest.md) for per-model SDK assignments, and [AI Inference Architecture](./ai-inference.md) for routing and fallback chains. + +--- + +## Consistency Rules + +To keep the ecosystem consistent: + +1. **360magicians org** projects → use `pnpm` +2. **pinkycollie / MBTQ-dev** projects → use `npm` +3. **PinkSync microservices** → use Deno (no node_modules) +4. **All `.env` files** → must be gitignored; use `.env.example` as template +5. **All Node.js projects** → pin to Node.js 20 LTS (specify in `.nvmrc` or `engines` in `package.json`) +6. **All pnpm projects** → include `pnpm-lock.yaml` in git; never commit `package-lock.json` +7. **All npm projects** → include `package-lock.json` in git; never commit `pnpm-lock.yaml` + +--- + +## Related + +- [Environments (dev → prod)](./environments.md) +- [Providers, Vendors & Resources](./providers.md) +- [Git Workflow](./git-workflow.md) diff --git a/docs/pipeline-handoffs.md b/docs/pipeline-handoffs.md new file mode 100644 index 0000000..5f8cb1e --- /dev/null +++ b/docs/pipeline-handoffs.md @@ -0,0 +1,447 @@ +# Pipeline Handoffs + +> Every agent-to-agent handoff point in the IDEA → BUILD → GROW → MANAGED pipeline: +> trigger, input contract, output contract, and the exact commands to run at each step. + +--- + +## Pipeline Overview + +``` + ┌────────────────────────────────────────────────────────────────────┐ + │ IDEA Stage BUILD Stage GROW Stage MANAGED │ + │ │ + │ issue (label:idea) │ + │ │ │ + │ IdeaMagician ──────► ValidatorMagician ──► ResearchMagician │ + │ │ │ │ + │ idea.json market_research.md │ + │ │ │ │ + │ DeveloperMagician ◄────────┘ │ + │ (build-001: create repo) │ + │ │ │ + │ ┌─────────┴──────────┐ │ + │ DesignMagician DeveloperMagician │ + │ (build-002) (build-004: backend) │ + │ │ │ │ + │ wireframes.svg backend_codebase.zip │ + │ │ │ │ + │ DeveloperMagician ◄────────┘ │ + │ (build-003: frontend) │ + │ │ │ + │ frontend_codebase.zip │ + │ │ │ + │ InfraMagician (build-005: deploy staging) │ + │ │ │ + │ staging_url │ + │ │ │ + │ ┌─────────┼──────────┐ │ + │ DataMagician GrowthMagician PartnershipMagician │ + │ (grow-001) (grow-002) (grow-003) │ + │ │ │ │ │ + │ dashboard_url campaign_report onboarding_status │ + │ └─────────┬──────────┘ │ + │ ▼ │ + │ ComplianceMagician / FinanceMagician / OpsMagician │ + │ (managed-001 / managed-002 / managed-003) │ + └────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Handoff 1: Human → IdeaMagician + +**Trigger:** GitHub Issue opened with label `idea` +**Or:** Direct API call + +### Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `prompt` | string | ✅ | Idea description (from issue title + body) | +| `target_audience` | string | ❌ | Optional audience hint | + +### Command + +```bash +# Via API +curl -X POST https://api.360magicians.com/idea \ + -H "Authorization: ******" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": "Deaf-first SaaS for municipal governance", + "target_audience": "Deaf community leaders" + }' + +# Via GitHub Issue +# Open issue with label "idea" — IdeaMagician picks it up automatically +``` + +### Output (`idea.json`) + +```json +{ + "idea_id": "idea-abc123", + "title": "Deaf Municipal Governance Platform", + "description": "...", + "target_audience": "Deaf community leaders", + "accessibility_features": ["ASL interface", "visual notifications", "captions"], + "suggested_tech_stack": "Next.js, TypeScript, Supabase", + "created_at": "2024-01-20T10:00:00Z" +} +``` + +### Handoff Signal + +IdeaMagician posts `idea.json` as a comment on the triggering issue and adds label `validate`. + +--- + +## Handoff 2: IdeaMagician → ValidatorMagician + +**Trigger:** Issue comment containing `idea.json` + label `validate` + +### Input + +`idea.json` (output from Handoff 1) + +### Command + +```bash +curl -X POST https://api.360magicians.com/idea/validate \ + -H "Authorization: ******" \ + -H "Content-Type: application/json" \ + -d @idea.json +``` + +### Output (`validation_report.json`) + +```json +{ + "idea_id": "idea-abc123", + "valid": true, + "compliance_score": 92, + "accessibility_score": 98, + "risks": [], + "recommendations": ["Add offline mode for low-bandwidth users"], + "approved_for_research": true +} +``` + +### Handoff Signal + +ValidatorMagician adds label `research` to the issue if `approved_for_research: true`. +On failure (`valid: false`) it adds label `needs-revision` and stops the pipeline. + +--- + +## Handoff 3: ValidatorMagician → ResearchMagician + +**Trigger:** Issue label `research` + +### Input + +| Field | Type | Required | +|-------|------|----------| +| `topic` | string | ✅ | +| `target_audience` | string | ✅ | + +### Command + +```bash +curl -X POST https://api.360magicians.com/idea/research \ + -H "Authorization: ******" \ + -H "Content-Type: application/json" \ + -d '{ + "topic": "Deaf Municipal Governance Platform", + "target_audience": "Deaf community leaders" + }' +``` + +### Output + +`market_research_report.md` — attached to the issue as a file comment. + +### Handoff Signal + +ResearchMagician adds label `build` to the issue. + +--- + +## Handoff 4: ResearchMagician → DeveloperMagician (build-001) + +**Trigger:** Issue label `build` + +### Input + +| Field | Type | Required | +|-------|------|----------| +| `project_name` | string | ✅ | +| `project_description` | string | ✅ | +| `tech_stack` | string | ❌ | + +### Command + +```bash +curl -X POST https://api.360magicians.com/build/repo \ + -H "Authorization: ******" \ + -H "Content-Type: application/json" \ + -d '{ + "project_name": "deaf-gov-platform", + "project_description": "Deaf-first municipal governance platform", + "tech_stack": "Next.js, TypeScript, Supabase" + }' +``` + +### Output + +```json +{ "repository_url": "https://github.com/360magicians/deaf-gov-platform" } +``` + +### Handoff Signal + +DeveloperMagician: +1. Creates the GitHub repo +2. Creates `main` + `develop` branches +3. Opens tracking issue in new repo linking back to original idea issue +4. Marks job `build-001` complete → API enqueues `build-002` and `build-004` in parallel + +--- + +## Handoff 5a: DeveloperMagician → DesignMagician (build-002) + +**Trigger:** `build-001` complete + +### Input + +`idea.json` + +### Command + +```bash +# DesignMagician calls the design endpoint (internal) +curl -X POST https://api.360magicians.com/build/design \ + -H "Authorization: ******" \ + -d @idea.json +``` + +### Output + +`wireframes.svg` — committed to `agent/build-002-wireframes` branch. + +### Handoff Signal + +DesignMagician opens PR `agent/build-002-wireframes` → `develop`. +On merge, marks `build-002` complete → API enqueues `build-003`. + +--- + +## Handoff 5b: DeveloperMagician → DeveloperMagician (build-004) + +**Trigger:** `build-001` complete (runs in parallel with build-002) + +### Input + +| Field | Type | +|-------|------| +| `api_specs.json` | derived from `idea.json` | +| `tech_stack` | string | + +### Output + +`backend_codebase.zip` — committed to `agent/build-004-backend` branch. + +### Handoff Signal + +PR `agent/build-004-backend` → `develop`. On merge → marks `build-004` complete. + +--- + +## Handoff 6: DesignMagician → DeveloperMagician (build-003) + +**Trigger:** `build-002` complete (wireframes merged) + +**`depends_on`: `["build-002"]`** + +### Input + +| Field | Type | +|-------|------| +| `wireframes.svg` | from `build-002` output | +| `tech_stack` | string | + +### Output + +`frontend_codebase.zip` — committed to `agent/build-003-frontend` branch. + +### Handoff Signal + +PR `agent/build-003-frontend` → `develop`. ValidatorMagician auto-reviews. +On merge → marks `build-003` complete. + +--- + +## Handoff 7: DeveloperMagician → InfraMagician (build-005) + +**Trigger:** Both `build-003` AND `build-004` complete + +**`depends_on`: `["build-003", "build-004"]`** + +### Input + +| Field | Type | +|-------|------| +| `frontend_codebase.zip` | from `build-003` | +| `backend_codebase.zip` | from `build-004` | + +### Commands + +```bash +# 1. Build Docker images +docker build -t gcr.io/mbtq-dev/deaf-gov-platform:$GIT_SHA . + +# 2. Push to GCR +docker push gcr.io/mbtq-dev/deaf-gov-platform:$GIT_SHA + +# 3. Deploy to staging +make deploy-mbtq-platform ENV=staging IMAGE_TAG=$GIT_SHA + +# 4. Wait for rollout +kubectl rollout status deployment/mbtq-platform -n staging + +# 5. Run smoke test +curl -f https://staging.deaf-gov-platform.mbtq.dev/api/health +``` + +### Output + +```json +{ "staging_url": "https://staging.deaf-gov-platform.mbtq.dev" } +``` + +### Handoff Signal + +InfraMagician marks `build-005` complete → API enqueues `grow-001`, `grow-002`, `grow-003`. + +--- + +## Handoff 8: InfraMagician → GROW Agents (parallel) + +### grow-001 — DataMagician + +**Trigger:** `build-005` complete + +```bash +curl -X POST https://api.360magicians.com/grow/analytics \ + -H "Authorization: ******" \ + -d '{ "app_url": "https://deaf-gov-platform.mbtq.dev", "kpis": ["dau", "accessibility_score"] }' +``` + +**Output:** `dashboard_url` + +--- + +### grow-002 — GrowthMagician + +```bash +curl -X POST https://api.360magicians.com/grow/campaign \ + -H "Authorization: ******" \ + -d @campaign_brief.md # Content-Type: text/markdown +``` + +**Output:** `campaign_report.md` + +--- + +### grow-003 — PartnershipMagician + +```bash +curl -X POST https://api.360magicians.com/grow/partners \ + -H "Authorization: ******" \ + -d @partner_list.csv +``` + +**Output:** `onboarding_status.json` + +--- + +## Handoff 9: GROW Agents → MANAGED Agents + +**Trigger:** All `grow-*` jobs complete + +### managed-001 — ComplianceMagician + +```bash +curl -X POST https://api.360magicians.com/managed/compliance \ + -H "Authorization: ******" \ + -d '{ "reporting_period": "2024-Q1" }' +``` + +**Output:** `compliance_report.pdf` URL + +--- + +### managed-002 — FinanceMagician + +```bash +curl -X POST https://api.360magicians.com/managed/finance \ + -H "Authorization: ******" \ + --data-binary @transactions.csv +``` + +**Output:** `financial_report.pdf` URL + +--- + +### managed-003 — OpsMagician + +```bash +curl -X POST https://api.360magicians.com/managed/ops \ + -H "Authorization: ******" \ + -d '{ "app_url": "https://deaf-gov-platform.mbtq.dev" }' +``` + +**Output:** `monitoring_dashboard_url` + +--- + +## Complete Handoff Table + +| # | From | To | Trigger | Input | Output | Signal | +|---|------|----|---------|-------|--------|--------| +| 1 | Human | IdeaMagician | Issue label `idea` | prompt | `idea.json` | Label `validate` | +| 2 | IdeaMagician | ValidatorMagician | Label `validate` | `idea.json` | `validation_report.json` | Label `research` or `needs-revision` | +| 3 | ValidatorMagician | ResearchMagician | Label `research` | topic + audience | `market_research_report.md` | Label `build` | +| 4 | ResearchMagician | DeveloperMagician | Label `build` | project spec | `repository_url` | Job `build-001` complete | +| 5a | DeveloperMagician | DesignMagician | `build-001` ✅ | `idea.json` | `wireframes.svg` | Job `build-002` complete | +| 5b | DeveloperMagician | DeveloperMagician | `build-001` ✅ | api specs | `backend_codebase.zip` | Job `build-004` complete | +| 6 | DesignMagician | DeveloperMagician | `build-002` ✅ | wireframes | `frontend_codebase.zip` | Job `build-003` complete | +| 7 | DeveloperMagician × 2 | InfraMagician | `build-003` ✅ + `build-004` ✅ | codebases | `staging_url` | Job `build-005` complete | +| 8a | InfraMagician | DataMagician | `build-005` ✅ | `app_url` | `dashboard_url` | Job `grow-001` complete | +| 8b | InfraMagician | GrowthMagician | `build-005` ✅ | `campaign_brief.md` | `campaign_report.md` | Job `grow-002` complete | +| 8c | InfraMagician | PartnershipMagician | `build-005` ✅ | `partner_list.csv` | `onboarding_status.json` | Job `grow-003` complete | +| 9a | GROW ✅ | ComplianceMagician | All grow jobs ✅ | `reporting_period` | `compliance_report.pdf` | Job `managed-001` complete | +| 9b | GROW ✅ | FinanceMagician | All grow jobs ✅ | `transactions.csv` | `financial_report.pdf` | Job `managed-002` complete | +| 9c | GROW ✅ | OpsMagician | All grow jobs ✅ | `app_url` | `monitoring_dashboard_url` | Job `managed-003` complete | + +--- + +## Failure Handling at Handoff Points + +| Scenario | Action | +|----------|--------| +| Job fails | Agent marks job `failed`, posts error as issue comment, adds label `needs-revision` | +| `depends_on` job timed out | Pipeline paused; `OpsMagician` alerts via monitoring dashboard | +| Validation rejected (PR changes requested) | Job re-queued; agent iterates on branch | +| Staging smoke test fails | `build-005` fails; `InfraMagician` rolls back Helm release | +| Webhook delivery fails | GitHub retries up to 3 times with exponential back-off | + +--- + +## Related + +- [Triggers, Webhooks & Prompts](./triggers-webhooks.md) +- [Copilot, Bots & Auth Access](./copilot-bots.md) +- [Git Workflow](./git-workflow.md) +- [Helm Deployment](./helm.md) diff --git a/docs/projects/deafauth.md b/docs/projects/deafauth.md new file mode 100644 index 0000000..1f43a34 --- /dev/null +++ b/docs/projects/deafauth.md @@ -0,0 +1,217 @@ +# DeafAuth + +Sources: [`360magicians/deafauth`](https://github.com/360magicians/deafauth) · [`MBTQ-dev/DeafAUTH`](https://github.com/MBTQ-dev/DeafAUTH) · [`DeafAUTH/readme.md`](https://github.com/DeafAUTH/readme.md) + +> Universal identity compiler — Web2/Web3 authentication & verification for Deaf-first platforms. + +--- + +## Overview + +**DeafAUTH** is the universal identity and access layer for the 360Magicians ecosystem. + +- Web2 & Web3 login (wallet-based) +- Role-based access control +- Magician agent role assignment +- API token security + +--- + +## Authentication + +### ****** + +```bash +export DEAFAUTH_TOKEN= +curl -H "Authorization: ******" \ + https://api.360magicians.com/jobs/list +``` + +### User Profile Schema + +```json +{ + "user_id": "deaf123", + "auth_type": "web3_wallet", + "permissions": ["IDEA_GENERATOR", "BUILD_ACCESS", "GROW_DASHBOARD"], + "profile": { + "display_name": "PinkMagician", + "language": "ASL", + "privacy": "private" + } +} +``` + +--- + +## Magician Jobs (Lifecycle API) + +### IDEA Stage + +| Job ID | Assigned To | Inputs | Outputs | +|-----------|---------------------|---------------------------------|----------------------------| +| `idea-001`| IdeaMagician | `prompt` | `idea.json` | +| `idea-002`| ValidatorMagician | `idea.json` | `validation_report.json` | +| `idea-003`| ResearchMagician | `topic`, `target_audience` | `market_research_report.md`| + +**Generate idea:** +```bash +curl -X POST https://api.360magicians.com/idea \ + -H "Authorization: ******" \ + -d '{"prompt": "Deaf-first SaaS idea"}' +``` + +--- + +### BUILD Stage + +| Job ID | Assigned To | Inputs | Outputs | +|------------|--------------------|-----------------------------------------|--------------------------| +| `build-001`| DeveloperMagician | `project_name`, `project_description` | `repository_url` | +| `build-002`| DesignMagician | `idea.json` | `wireframes.svg` | +| `build-003`| DeveloperMagician | `wireframes.svg`, `tech_stack` | `frontend_codebase.zip` | +| `build-004`| DeveloperMagician | `api_specs.json`, `tech_stack` | `backend_codebase.zip` | +| `build-005`| InfraMagician | `frontend_codebase.zip`, `backend_codebase.zip` | `staging_url` | + +--- + +### GROW Stage + +| Job ID | Assigned To | Inputs | Outputs | +|------------|-----------------------|----------------------|--------------------------| +| `grow-001` | DataMagician | `app_url`, `kpis` | `dashboard_url` | +| `grow-002` | GrowthMagician | `campaign_brief.md` | `campaign_report.md` | +| `grow-003` | PartnershipMagician | `partner_list.csv` | `onboarding_status.json` | + +--- + +### MANAGED Stage + +| Job ID | Assigned To | Inputs | Outputs | +|---------------|---------------------|----------------------|-------------------------------| +| `managed-001` | ComplianceMagician | `reporting_period` | `compliance_report.pdf` | +| `managed-002` | FinanceMagician | `transactions.csv` | `financial_report.pdf` | +| `managed-003` | OpsMagician | `app_url` | `monitoring_dashboard_url` | + +--- + +## Job Dependencies + +Jobs support sequential orchestration via `depends_on`: + +```json +{ + "job_id": "build-003", + "depends_on": ["build-002"] +} +``` + +This ensures **frontend development waits for wireframes**. + +--- + +## Tech Stack + +Built with Next.js (TypeScript), shadcn/ui, Tailwind CSS, Firebase. + +Key source files: +- `src_firebase_Version2.js` — Firebase config +- `src_components_Auth_Version2.js` — Auth UI components +- `src_hooks_useAccommodations_Version2.js` — Accessibility hooks +- `functions_index_Version2.js` — Cloud Functions entry point + +--- + +## DeafAUTH SDK (MBTQ-dev/DeafAUTH) + +The [MBTQ-dev/DeafAUTH](https://github.com/MBTQ-dev/DeafAUTH) repository is the **universal identity compiler** — a framework-agnostic protocol that aggregates authentication from multiple sources into a single Deaf-first identity hub. + +> **Not a framework. Not a library. A protocol.** + +### Core Concept + +``` +┌─────────────────────────────────────────┐ +│ Your Existing Auth Systems │ +│ (Auth0, Google, Work SSO, School, IoT) │ +└──────────────┬──────────────────────────┘ + │ + ▼ + ┌────────────┐ + │ DeafAUTH │ ← Compiles ALL into ONE + │ Compiler │ with Deaf-first defaults + └──────┬─────┘ + │ + ▼ + ┌───────────────────────┐ + │ One Identity │ + │ Infinite Access │ + │ Accessibility Synced │ + └───────────────────────┘ +``` + +### Quick Start + +```typescript +import { DeafAUTH } from '@deafauth/core'; + +const deafauth = new DeafAUTH({ apiUrl: 'https://api.deafauth.mbtq.dev' }); + +const user = await deafauth.register({ + email: 'user@example.com', + password: 'secure-password', + name: 'John Doe' + // Automatically includes: deaf_status, preferred_language: 'ASL', + // communication_preference: 'visual', accessibility_needs: [] +}); +``` + +### API Endpoints + +``` +POST /v1/register # Create DeafAUTH identity +POST /v1/login # Authenticate user +POST /v1/validate-deaf # Validate Deaf identity +POST /v1/connect-system # Link external auth system +GET /v1/user/:id # Get user profile +PATCH /v1/user/:id # Update preferences +DELETE /v1/user/:id # Delete identity +``` + +### SDKs + +| Language | Package | Install | +|----------|---------|---------| +| JavaScript/TypeScript | `@deafauth/core` | `npm install @deafauth/core` | +| Python | `deafauth` | `pip install deafauth` | +| Go | `github.com/deafauth/go-sdk` | `go get github.com/deafauth/go-sdk` | +| PHP | `deafauth/php-sdk` | `composer require deafauth/php-sdk` | +| Ruby | `deafauth` | `gem install deafauth` | +| Rust | `deafauth` | `cargo add deafauth` | + +### Integration Patterns + +**OAuth Wrapper** — Wrap existing OAuth with DeafAUTH to add Deaf preferences: +``` +User → Your App → DeafAUTH → Auth0/Google + ↓ + Deaf preferences stored & synced +``` + +**Identity Hub** — Central hub for all authentications: +``` +Work SSO ─┐ +School ─┼→ DeafAUTH → Your App (Single identity + Accessibility) +IoT ─┘ +``` + +**Microservices** — Each service checks DeafAUTH: +``` +Service A ─┐ +Service B ─┼→ DeafAUTH API (validates token + returns preferences) +Service C ─┘ +``` + +- **API Docs:** [api.deafauth.mbtq.dev/docs](https://api.deafauth.mbtq.dev/docs) +- **Website:** [deafauth.mbtq.dev](https://deafauth.mbtq.dev) + diff --git a/docs/projects/fibonrose.md b/docs/projects/fibonrose.md new file mode 100644 index 0000000..edd7d50 --- /dev/null +++ b/docs/projects/fibonrose.md @@ -0,0 +1,58 @@ +# FibonRose + +Source: [`360magicians/fibonrose`](https://github.com/360magicians/fibonrose) · branch `ux/ui` + +> Next.js UI application — part of the Deaf-First platform suite. + +--- + +## Overview + +FibonRose is a Next.js TypeScript application built with shadcn/ui components. It forms part of the +360Magicians Deaf-First platform family. + +--- + +## Tech Stack + +| Technology | Purpose | +|----------------|------------------------| +| Next.js | React framework | +| TypeScript | Type safety | +| shadcn/ui | Component library | +| Tailwind CSS | Utility-first styling | +| pnpm | Package manager | + +--- + +## Project Structure + +``` +fibonrose/ +├── app/ # Next.js App Router pages +├── components/ # Shared UI components +├── hooks/ # Custom React hooks +├── lib/ # Utilities +├── public/ # Static assets +├── scripts/ # Build/utility scripts +└── styles/ # Global styles +``` + +--- + +## Getting Started + +```bash +# Install dependencies +pnpm install + +# Start development server +pnpm dev +``` + +--- + +## Related + +- [360Magicians About](../about.md) +- [PinkSync (accessibility layer)](./pinksync.md) diff --git a/docs/projects/mbtq-dev.md b/docs/projects/mbtq-dev.md new file mode 100644 index 0000000..c8d5eb8 --- /dev/null +++ b/docs/projects/mbtq-dev.md @@ -0,0 +1,98 @@ +# MBTQ.dev + +Source: [`pinkycollie/mbtq-dev`](https://github.com/pinkycollie/mbtq-dev) + +> AI-powered full-stack development platform — accessible starter kit for LGBTQ+ and Deaf communities. + +--- + +## Overview + +**MBTQ.dev** is a transparent generative AI development starter that powers full-stack applications with modern tools for visual design creation and communication. Originally built to support Deaf entrepreneurs, it now serves as an educational and starter kit platform. + +Live Demo: [pinkycollie.github.io/mbtq-dev](https://pinkycollie.github.io/mbtq-dev/) + +--- + +## Key Features + +- **Generative AI Integration** — Templates integrating GPT-4, Claude, and Gemini +- **Backend Connectors** — Supabase auth, database, storage, and edge functions +- **Accessibility First** — WCAG compliant, visual notifications, caption widget, high-contrast toggle +- **Movable/Resizable Widgets** — Interact.js drag-and-drop workspace +- **Real-time Multiuser Sync** — Socket.IO collaboration +- **Quinn AI Assistant** — AI agent with Fibonrose task validation +- **Content Fulfillment API** — Full-stack API for video requests and creator fulfillment + +--- + +## AI Development Assistant (Quinn) + +Quinn is an AI agent powered by the **Fibonrose Task Validation System**: + +- Code architecture guidance +- Feature implementation assistance +- Debugging help +- PR review and suggestions +- Documentation generation + +### Fibonrose Task Validation + +Tasks are validated with Fibonacci-based checkpoints scaled by complexity: + +| Complexity | Confirmations | Example | +|-----------|---------------|---------| +| 0–1 | 1 | Fix typo, update docs | +| 2 | 2 | Add component prop, update config | +| 3 | 3 | Create UI component, add API endpoint | +| 4 | 5 | Implement feature with tests | +| 5 | 8 | Build complete feature | +| 6+ | 13+ | Major architectural changes | + +--- + +## Tech Stack + +| Technology | Purpose | +|-----------|---------| +| React 18 + TypeScript | Frontend UI | +| Vite | Build tooling | +| Tailwind CSS | Styling | +| Socket.IO | Real-time collaboration | +| PostgreSQL + Prisma ORM | Database | +| Supabase | Auth, storage, edge functions | +| axe-core | Accessibility testing | + +--- + +## Architecture + +``` +mbtq-dev/ +├── client/ # React UI with drag-and-drop widgets +├── server/ # TypeScript REST API +│ ├── routes/ # API routes +│ ├── models/ # Prisma models +│ └── hooks/ # Business logic +└── docs/ # Guides and references +``` + +--- + +## Getting Started + +```bash +# Client +cd client && npm install && npm run dev + +# Server +cd server && npm install && npm run dev +``` + +--- + +## Related + +- [PinkSync (accessibility layer)](./pinksync.md) +- [DeafAuth (identity layer)](./deafauth.md) +- [Infrastructure Docs](../infrastructure.md) diff --git a/docs/projects/mbtquniverse.md b/docs/projects/mbtquniverse.md new file mode 100644 index 0000000..56df7dc --- /dev/null +++ b/docs/projects/mbtquniverse.md @@ -0,0 +1,172 @@ +# MBTQUniverse + +Source: [`pinkycollie/mbtquniverse`](https://github.com/pinkycollie/mbtquniverse) + +> Decentralized platform for DAO governance, tokenization, agent/project registration, staking, and metrics. + +--- + +## Overview + +MBTQUniverse is a **clean, decentralized platform** for DAO governance, tokenization systems, agent/project registration, staking, and metrics tracking. Built without third-party company integrations for maximum transparency and independence. It serves as the Web3/DAO layer of the MBTQ ecosystem. + +--- + +## Platform Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ MBTQUniverse Platform │ +├─────────────────────────────────────────────────────────┤ +│ Tokenization │ DAO Governance │ Agent Registry │ +│ & Stablecoin │ │ (Projects) │ +├─────────────────────────────────────────────────────────┤ +│ Staking │ Metrics │ API Gateway │ +│ & Rewards │ & Analytics │ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## Key Features + +### 1. Tokenization & Stablecoin System + +Framework for digital asset management: + +```javascript +const fdd = platform.stablecoin.createStablecoin({ + name: 'Federal Digital Dollar', + symbol: 'FDD', + backingAsset: 'USD', + initialSupply: 1000000, + issuer: 'Federal Reserve', + complianceLevel: 'federal' +}); +``` + +- 1:1 backing with traditional assets +- Full transparency and audit trails +- Multi-signature authorization + +### 2. DAO Governance + +```javascript +const proposal = platform.dao.createProposal({ + title: 'Increase Staking Rewards', + proposerId: 'member-001', + votingPeriod: 7 * 24 * 60 * 60 * 1000 // 7 days +}); +platform.dao.vote(proposal.id, 'member-001', 'for'); +platform.dao.finalizeProposal(proposal.id); +``` + +- Token-weighted or role-based voting +- Customizable quorum and approval thresholds +- Execution delays for security + +### 3. Agent & Project Registry + +```javascript +const agent = platform.registry.registerAgent({ + name: 'Governance Bot', + capabilities: ['monitoring', 'notifications'], + owner: 'org-001' +}); +``` + +### 4. Staking & Incentives + +```javascript +const pool = platform.staking.createPool({ + name: 'Governance Staking', + tokenSymbol: 'FDD', + rewardRate: 0.05 // 5% APY +}); +platform.staking.stake(pool.id, 'user-001', 5000); +``` + +### 5. Metrics & Analytics + +```javascript +platform.metrics.recordEvent({ + type: 'governance', + actor: 'member-001', + action: 'proposal_created' +}); +const dashboard = platform.metrics.getDashboardData(); +``` + +--- + +## Project Structure + +``` +mbtquniverse/ +├── src/ +│ ├── tokenization/ # Stablecoin and asset management +│ ├── dao/ # Governance system +│ ├── registry/ # Agent and project directory +│ ├── staking/ # Staking and rewards +│ ├── api/ # API gateway +│ ├── metrics/ # Analytics and metrics +│ └── index.js # Main entry point +├── docs/ # Documentation +├── diagrams/ # Architecture diagrams +├── config/ # Configuration files +└── examples/ # Usage examples +``` + +--- + +## Quick Start + +```bash +git clone https://github.com/pinkycollie/mbtquniverse.git +cd mbtquniverse +npm install +npm start +``` + +--- + +## Security & Compliance + +- Multi-signature authorization for critical operations +- Complete audit trails for all transactions +- Rate limiting and DDOS protection +- Real-time reserve backing verification +- Role-based access control + +--- + +## Ecosystem Context + +The DAO sits within the **mbtquniverse.com** platform: +- `dao-governance` +- `web3-staking` +- `showcase-projects` +- `community-treasury` + +--- + +## Roadmap + +- [x] Core tokenization system +- [x] DAO governance framework +- [x] Agent and project registry +- [x] Staking and rewards system +- [x] Metrics and analytics +- [x] API gateway +- [ ] Database persistence layer +- [ ] Multi-chain support +- [ ] Identity verification integration +- [ ] Mobile interfaces + +--- + +## Related + +- [Infrastructure Docs](../infrastructure.md) +- [DeafAuth (identity layer)](./deafauth.md) +- [Municipal DAO](./municipal-dao.md) diff --git a/docs/projects/municipal-dao.md b/docs/projects/municipal-dao.md new file mode 100644 index 0000000..1be6a08 --- /dev/null +++ b/docs/projects/municipal-dao.md @@ -0,0 +1,169 @@ +# Municipal DAO + +Source: [`360magicians/municipal-dao`](https://github.com/360magicians/municipal-dao) + +> On-chain governance DAO platform with real-time WebSocket voting and notifications. + +--- + +## Overview + +Municipal DAO is a decentralized governance platform that enables Deaf communities and municipal +stakeholders to participate in transparent, real-time on-chain voting. + +--- + +## Real-Time WebSocket Integration + +### Features + +#### 🔄 Real-Time Voting +- Live vote counting with animated updates +- Quorum progress tracking with visual indicators +- Recent votes display (who voted and when) +- Live viewer count for active proposal watchers +- Instant vote casting with real-time feedback + +#### 🔔 Real-Time Notifications +- Instant notifications for votes, comments, and system updates +- Priority-based alerts (low, medium, high) +- Browser notifications for high-priority items +- Connection status indicators showing WebSocket health +- Notification management (mark as read, clear, etc.) + +#### 🌐 WebSocket Infrastructure +- Robust connection management with auto-reconnection +- Room-based messaging for proposal-specific updates +- Message type routing for different notification types +- Authentication integration with user sessions +- Error handling and recovery for network issues + +--- + +## Technical Architecture + +### Client-Side + +| File | Purpose | +|------|---------| +| `lib/websocket.ts` | Singleton WebSocket connection manager with exponential backoff | +| `hooks/useRealTimeVoting.ts` | Live vote count updates, quorum tracking, vote casting | +| `hooks/useRealTimeNotifications.ts` | Notification state, browser notifications, read/unread status | +| `components/RealTimeVotingCard` | Animated voting interface | +| `components/RealTimeNotifications` | Notification dropdown with live updates | + +### Server-Side + +- **Node.js WebSocket server** — `server/websocket-server.js` +- Room management for proposal-specific messaging +- Message broadcasting to relevant users +- Authentication verification +- Graceful shutdown handling + +--- + +## Getting Started + +```bash +# Install dependencies +npm install + +# Start the WebSocket server (development) +npm run ws-server + +# Start the Next.js application +npm run dev +``` + +--- + +## Environment Variables + +```env +# WebSocket server configuration +WS_PORT=8080 +WS_HOST=localhost + +# Production WebSocket URL +NEXT_PUBLIC_WS_URL=wss://your-domain.com/ws +``` + +--- + +## Message Types + +### Vote Message +```json +{ + "type": "vote", + "data": { + "proposalId": "1", + "userId": "alice.eth", + "choice": "for", + "votingPower": 12.5, + "reason": "Strong proposal with clear benefits" + }, + "timestamp": "2024-01-20T10:30:00Z" +} +``` + +### Notification Message +```json +{ + "type": "notification", + "data": { + "id": "notification-123", + "type": "vote", + "title": "New Vote Cast", + "message": "alice.eth voted FOR on Marketing Budget proposal", + "priority": "medium", + "actionUrl": "/proposals/1" + }, + "timestamp": "2024-01-20T10:30:00Z" +} +``` + +### System Message (quorum reached) +```json +{ + "type": "quorum_reached", + "data": { + "proposalId": "1", + "quorum": 51.2, + "proposalTitle": "Marketing Budget Allocation" + }, + "timestamp": "2024-01-20T10:30:00Z" +} +``` + +--- + +## Security + +1. **Authentication** — All WebSocket connections require valid user authentication +2. **Rate Limiting** — Prevent spam +3. **Input Validation** — All incoming messages are validated +4. **CORS Configuration** — Proper CORS setup for cross-origin requests +5. **SSL/TLS** — Use secure WebSocket connections (`wss://`) in production + +--- + +## Ecosystem Architecture + +The DAO sits within the **mbtquniverse.com** platform: +- `dao-governance` +- `web3-staking` +- `showcase-projects` +- `community-treasury` + +See [Infrastructure Docs](../infrastructure.md) for full ecosystem context. + +--- + +## Future Enhancements + +- Horizontal scaling via Redis-based message broadcasting +- Message persistence for offline users +- User-customizable notification preferences +- Mobile push notification integration +- Real-time analytics dashboard diff --git a/docs/projects/pinksync.md b/docs/projects/pinksync.md new file mode 100644 index 0000000..53b595c --- /dev/null +++ b/docs/projects/pinksync.md @@ -0,0 +1,125 @@ +# PinkSync + +Sources: [`360magicians/pinksync`](https://github.com/360magicians/pinksync) · [`PinkSync/PinkSync`](https://github.com/PinkSync/PinkSync) · [`PinkSync/Core-principles`](https://github.com/PinkSync/Core-principles) + +> Accessibility layer + real-time sync engine · Layer 1 accessibility orchestration platform · Deaf-first API broker. + +--- + +## Overview + +PinkSync is the **Accessibility AI Middleware** of the 360Magicians ecosystem. It bridges AI services +with accessible delivery across visual, tactile, sign-language, and high-contrast modalities. + +**Core services:** +- `ai-transformation` — Transform AI outputs into accessible formats +- `accessibility-layer` — Apply modality-specific transformations +- `data-synchronization` — Keep data consistent across devices +- `offline-sync` — Queue and replay updates when offline +- `cross-platform-delivery` — Deliver content to web, mobile, and VR + +--- + +## Infrastructure + +Kubernetes: 3 replicas · `gcr.io/mbtq-dev/pinksync-accessibility:latest` · port 8081 + +Environment variables: +``` +DEAFAUTH_API_URL=https://deafauth.mbtq.dev +VERTEX_AI_ENDPOINT=https://api.360magicians.com +OFFLINE_SYNC_ENABLED=true +ACCESSIBILITY_TRANSFORMS=visual,tactile,sign-language,high-contrast +``` + +--- + +## Tech Stack + +Built with Next.js (TypeScript), shadcn/ui, Tailwind CSS. +- `app/` — Next.js App Router pages +- `backend/` — Backend services +- `browser-extension/` — Browser extension for accessibility overlays +- `components/` — Shared UI components +- `contexts/` — React context providers +- `hooks/` — Custom hooks + +--- + +## PinkSync Platform (PinkSync/PinkSync) + +The [PinkSync/PinkSync](https://github.com/PinkSync/PinkSync) repository is the comprehensive Layer 1 platform. It acts as a unified gateway connecting Deaf communities with accessible services while providing real-time accessibility enhancements. + +### Two Primary Components + +**DeafAUTH Backend (The Brain)** +- Centralized authentication and preference management +- API gateway for service integrations +- Real-time content transformation engine + +**PinkSync Browser Extension (The Hands)** +- Chrome extension that runs on every website +- Automatically applies accessibility preferences +- Enables captions on all video platforms +- Converts audio alerts to visual notifications +- Auto-fills accessibility forms + +### Microservices + +| Service | Purpose | +|---------|---------| +| `deafauth` | Visual-first authentication and preference management | +| `event-orchestrator` | Node-based event listener and processing | +| `rag-engine` | Research-Augmented Generation for accessibility learning | +| `workers` | Background job processors for automation | +| `api-broker` | Unified gateway for partner service integrations | +| `pinkflow` | Real-time accessibility adjustment engine | +| `asl-glosser` | ASL glossing and sign language processing | +| `sign-speak` | Multi-language sign language recognition | +| `vcode` | Deaf-first video communication | +| `interpreters` | Interpreter booking and management | + +> Powered by Deno for lightweight runtime — no build step, native TypeScript support. + +--- + +## PinkSync API Broker (PinkSync/Core-principles) + +The [PinkSync/Core-principles](https://github.com/PinkSync/Core-principles) repository defines PinkSync as an **accessibility API broker** — "Stripe, but for accessibility signals." + +### Core Philosophy + +> **Not a Deaf app. A Deaf-first protocol.** + +PinkSync operates as an **accessibility signal exchange**: + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/v1/events` | POST | Accept accessibility events from applications | +| `/v1/capabilities` | GET | List registered application capabilities | +| `/v1/subscribe` | POST | Subscribe to accessibility events | +| `/v1/compliance/{app_id}` | GET | Check compliance status | +| `/v1/validate` | POST | Validate target for compliance | +| `/v1/context/initialize` | POST | Initialize accessibility context | + +### Compliance Levels + +Bronze → Silver → Gold → Platinum — each tier enforces more stringent contract requirements with machine-verifiable signals and cryptographically signed audit logs. + +```python +# Submit accessibility event +event = { + "app_id": "my-app-v2", + "user_id": "user-12345", + "intent": "visual_only", + "compliance_level": "gold" +} +response = httpx.post("https://api.pinksync.io/v1/events", json=event) +``` + +--- + +## Related + +- [Infrastructure Docs](../infrastructure.md) +- [DeafAuth (identity layer)](./deafauth.md) diff --git a/docs/projects/railway-template.md b/docs/projects/railway-template.md new file mode 100644 index 0000000..f21f2b9 --- /dev/null +++ b/docs/projects/railway-template.md @@ -0,0 +1,128 @@ +# Railway Next.js Template + +Source: [`360magicians/railway_nextjs_with_shadcn`](https://github.com/360magicians/railway_nextjs_with_shadcn) + +> Production-ready Next.js starter with Screaming Architecture, Server Actions, and zero-config Railway deployment. + +[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/nextjs-155-server-actions-with-shadcn?referralCode=fvqeo8) + +--- + +## Key Features + +- **Screaming Architecture** — Business logic organized by domain +- **Server Actions** — Zero API routes for auth; uses Next.js 15 server actions +- **Amber Minimal Theme** — Pre-configured shadcn/ui design system +- **Complete Auth Flows** — Signup, login, forgot/reset password, email verification +- **Railway-Native** — Health checks, graceful shutdown, zero-config deploy +- **Type Safety** — Zod runtime validation, TypeScript throughout + +--- + +## Tech Stack + +| Technology | Version | Purpose | +|---------------------|----------|--------------------------| +| Next.js | 15.5.4 | React framework | +| React | 19.2.0 | UI library | +| TypeScript | 5.9.3 | Type safety | +| Tailwind CSS | 4.1.14 | Styling | +| shadcn/ui | Latest | Component library | +| Zod | 4.1.11 | Runtime validation | +| React Hook Form | 7.64.0 | Form management | +| bcryptjs | 3.0.2 | Password hashing | +| Sonner | 2.0.7 | Toast notifications | + +--- + +## Project Structure + +``` +src/ +├── app/ # Next.js App Router +│ ├── (auth)/ # Auth pages +│ ├── dashboard/ # Protected dashboard +│ └── api/health|system/ # Railway health checks +├── features/ # Business logic by domain +│ ├── auth/ # Authentication +│ │ ├── actions/ # Server actions (NO API routes) +│ │ ├── components/ # Auth UI +│ │ ├── lib/ # Utilities (password hashing) +│ │ └── types/ # Zod schemas & TS types +│ ├── dashboard/ +│ ├── home/ +│ └── health/ +├── components/ui/ # shadcn/ui components +├── core/config/ # Environment validation +└── infrastructure/logging/ # Logging utilities +``` + +--- + +## Quick Start + +```bash +# Clone and install +git clone https://github.com/360magicians/railway_nextjs_with_shadcn +cd railway_nextjs_with_shadcn +npm install + +# Run dev server +npm run dev +``` + +Demo credentials: `demo@example.com` / `password123` +Email verification code: `123456` + +--- + +## Server Actions Pattern + +```typescript +// 1. Shared Zod schema +export const signupSchema = z.object({ + email: z.string().email(), + password: z.string().min(8), + confirmPassword: z.string(), +}).refine((data) => data.password === data.confirmPassword); + +// 2. Server Action +'use server'; +export async function signupAction(_prevState, formData: FormData) { + const result = signupSchema.safeParse({ ... }); + if (!result.success) return { success: false, errors: result.error }; + // Hash password, create user, etc. + return { success: true, message: 'Account created!' }; +} + +// 3. Client form hooks into the action +const [state, formAction] = useFormState(signupAction, null); +``` + +--- + +## Documentation + +| Guide | Description | +|-------|-------------| +| [SETUP.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/SETUP.md) | Detailed setup instructions | +| [ARCHITECTURE.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/ARCHITECTURE.md) | Why it's structured this way | +| [SERVER_ACTIONS_GUIDE.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/SERVER_ACTIONS_GUIDE.md) | Complete server actions guide | +| [DEPLOYMENT.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/DEPLOYMENT.md) | Railway deployment guide | +| [MIGRATION_CHECKLIST.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/MIGRATION_CHECKLIST.md) | Step-by-step migration guide | +| [API_ROUTES_CLEANUP_GUIDE.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/docs/API_ROUTES_CLEANUP_GUIDE.md) | API routes vs server actions | +| [CHANGELOG.md](https://github.com/360magicians/railway_nextjs_with_shadcn/blob/main/CHANGELOG.md) | Version history | + +--- + +## Deployment (Railway) + +1. Click the deploy button above +2. Set environment variables (optional) +3. Deploy — Railway auto-detects Next.js via Railpack + +Railway provides: +- Health checks on `/api/health` +- System monitoring on `/api/system` +- Graceful SIGTERM shutdown +- `HOSTNAME=0.0.0.0` for container networking diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 0000000..03d781c --- /dev/null +++ b/docs/providers.md @@ -0,0 +1,143 @@ +# AI Providers, Vendors & Resources + +> Reference for all AI providers, platform vendors, and resource types used across the 360Magicians / MBTQ ecosystem — classified as open-source, proprietary, or custom-built. + +--- + +## AI Providers + +| Provider | Model(s) | Classification | Used By | +|----------|---------|----------------|---------| +| **Google Vertex AI** | Gemini, PaLM | Proprietary | 360magicians.com hub, mbtq.dev | +| **Google AI Studio** | Gemini | Proprietary | mbtq.dev (Gemini CLI bridge) | +| **OpenAI** | GPT-4, GPT-4o | Proprietary | mbtq-dev templates, Quinn AI | +| **Anthropic** | Claude (all versions) | Proprietary | Quinn AI, agent review | +| **Grok** | Grok | Proprietary | Ecosystem partner | +| **Groq** | Mixtral, Llama 3 | Proprietary (inference) | Fast inference layer | +| **Fal** | Image / video models | Proprietary | Content generation, Deaf media | +| **HuggingFace** | Llama 3, Mistral, Whisper, CLIP, SDXL, embeddings | Open Source (HF Hub) | PinkSync, DeafAuth, local dev, fallback inference | + +### Provider Selection by Stage + +| Stage | Preferred Provider | Reason | +|-------|--------------------|--------| +| IDEA | OpenAI / Gemini | Creative generation | +| BUILD | Anthropic (Claude) | Code generation, architecture | +| GROW | OpenAI | Marketing copy, analytics summaries | +| MANAGED | Gemini (Vertex AI) | Compliance, data analysis at scale | + +--- + +## Platform Vendors + +### Cloud & Infrastructure + +| Vendor | Service | Classification | Used By | +|--------|---------|----------------|---------| +| **Google Cloud (GCP)** | GKE, GCR, Secret Manager, Vertex AI | Proprietary | Full ecosystem (project: `mbtq.dev`) | +| **Railway** | PaaS deployment, health checks | Proprietary | `railway_nextjs_with_shadcn`, quick deploys | +| **Supabase** | Auth, PostgreSQL, storage, edge functions | Open Source (self-hostable) | mbtq-dev, general projects | +| **Firebase** | Auth, Firestore, Cloud Functions | Proprietary | DeafAuth (firebase version) | +| **Neon** | Serverless PostgreSQL | Proprietary | Ecosystem partner | + +### Auth & Identity + +| Vendor | Service | Classification | Used By | +|--------|---------|----------------|---------| +| **Auth0** | Enterprise OAuth/OIDC | Proprietary | DeafAUTH OAuth wrapper integration | +| **DeafAUTH** | Deaf-first identity compiler | **Custom** | All ecosystem services | +| **Web3 Wallets** | Wallet-based auth (EVM) | Open Protocol | MBTQUniverse, DAO governance | + +### Developer Tools + +| Vendor | Service | Classification | Used By | +|--------|---------|----------------|---------| +| **v0 (Vercel)** | AI UI generation | Proprietary | mbtq.dev (v0-studio-integration) | +| **Cursor AI** | AI code editor | Proprietary | Developer tooling | +| **GitHub** | Repos, Actions, GraphQL API | Proprietary (free tier) | All repos | +| **Redocly** | API docs / OpenAPI rendering | Proprietary (free tier) | This docs repo | + +--- + +## Open-Source Dependencies + +### Frameworks & Runtimes + +| Package | Version | Runtime | Projects | +|---------|---------|---------|---------| +| **Next.js** | 15.x | Node.js | FibonRose, DeafAuth, PinkSync, Railway template | +| **React** | 19.x | Browser / Node.js | All Next.js projects | +| **Deno** | 1.x | Deno runtime | PinkSync microservices | +| **Fresh** | 1.x | Deno | PinkSync (lightweight Deno web framework) | +| **Vite** | 5.x | Node.js | mbtq-dev client | + +### UI & Styling + +| Package | Classification | Projects | +|---------|---------------|---------| +| **shadcn/ui** | Open Source (MIT) | FibonRose, Railway template, DeafAuth, PinkSync | +| **Tailwind CSS** | Open Source (MIT) | All Next.js projects | +| **Interact.js** | Open Source (MIT) | mbtq-dev (drag-and-drop widgets) | + +### Backend & Data + +| Package | Classification | Projects | +|---------|---------------|---------| +| **Prisma ORM** | Open Source (Apache 2.0) | mbtq-dev server | +| **Socket.IO** | Open Source (MIT) | mbtq-dev (real-time collab), PinkSync | +| **PostgreSQL** | Open Source (PostgreSQL License) | mbtq-dev, Supabase projects | +| **axe-core** | Open Source (MPL 2.0) | mbtq-dev (accessibility testing) | + +### Validation & Utilities + +| Package | Classification | Projects | +|---------|---------------|---------| +| **Zod** | Open Source (MIT) | Railway template, DeafAuth | +| **React Hook Form** | Open Source (MIT) | Railway template | +| **bcryptjs** | Open Source (MIT) | Railway template (password hashing) | + +--- + +## Proprietary & Custom Components + +### Custom-Built (360Magicians / MBTQ) + +| Component | Repo | Purpose | +|-----------|------|---------| +| **DeafAUTH** | `MBTQ-dev/DeafAUTH` | Universal Deaf-first identity compiler (custom protocol) | +| **PinkSync API Broker** | `PinkSync/Core-principles` | Accessibility signal exchange (custom protocol) | +| **Magician Agents** | `MBTQ-dev/Magician_Platform` | IDEA→BUILD→GROW→MANAGED lifecycle agents | +| **Quinn AI** | `pinkycollie/mbtq-dev` | Dev assistant with Fibonacci task validation | +| **MBTQUniverse DAO** | `pinkycollie/mbtquniverse` | Custom on-chain governance framework | +| **FibonRose Task Validation** | `360magicians/fibonrose` | Fibonacci-scaled confirmation system | + +### Proprietary AI Services (vendor-locked) + +| Service | Vendor | Alternative (open source) | +|---------|--------|--------------------------| +| Vertex AI | Google | Ollama + open LLMs | +| GPT-4 | OpenAI | Llama 3 (via Groq or local) | +| Claude | Anthropic | Mistral (self-hosted) | +| Firebase Auth | Google | Supabase Auth (open source) | +| v0 | Vercel | Lovable.dev, open UI generators | + +--- + +## Resource Summary by Environment + +| Resource Type | Dev | Staging | Prod | +|--------------|-----|---------|------| +| AI provider | Mock / local Ollama | Vertex AI (lower quota) | Vertex AI + OpenAI + Claude | +| Database | Local PostgreSQL or Supabase free | Supabase project | Supabase / Neon paid tier | +| Auth | DeafAUTH dev instance | DeafAUTH staging | DeafAUTH prod | +| K8s | Local (kind / minikube) | GKE staging cluster | GKE prod cluster (`mbtq.dev`) | +| Container registry | Local | `gcr.io/mbtq-dev/*:staging-*` | `gcr.io/mbtq-dev/*:` | +| Secrets | `.env.local` files | GCP Secret Manager (staging) | GCP Secret Manager (prod) | + +--- + +## Related + +- [Environments (dev → prod)](./environments.md) +- [Package Managers & Runtimes](./package-managers.md) +- [Infrastructure / Ecosystem Architecture](./infrastructure.md) diff --git a/docs/triggers-webhooks.md b/docs/triggers-webhooks.md new file mode 100644 index 0000000..3192bc7 --- /dev/null +++ b/docs/triggers-webhooks.md @@ -0,0 +1,396 @@ +# Triggers, Webhooks & Prompts + +> Complete reference for every event trigger, webhook configuration, payload schema, HMAC verification, +> and prompt pattern used across the 360Magicians MBTQ ecosystem. + +--- + +## Overview + +The ecosystem uses three trigger layers: + +| Layer | Mechanism | Who listens | +|-------|-----------|-------------| +| **GitHub Webhooks** | HTTP POST from GitHub to agent receiver | Magician agents, CI bots | +| **API-Level Triggers** | Job completion callbacks from `api.360magicians.com` | Downstream Magician agents | +| **Prompt Triggers** | Issue labels, PR comments, chat commands | Copilot, Quinn AI, bots | + +--- + +## GitHub App — Setup + +All Magician agents authenticate to GitHub as a **GitHub App** (not a personal token). +This gives fine-grained, per-repo permissions that can be audited and revoked. + +### App Registration + +1. Go to **GitHub → Settings → Developer settings → GitHub Apps → New GitHub App** +2. Fill in: + + ``` + App name: 360Magicians Bot + Homepage URL: https://360magicians.com + Webhook URL: https://api.360magicians.com/webhooks/github + Webhook secret: + ``` + +3. Permissions required: + + | Permission | Level | Reason | + |-----------|-------|--------| + | Contents | Read & Write | Push branches, read files | + | Pull requests | Read & Write | Open PRs, post reviews | + | Issues | Read & Write | Create/update tracking issues | + | Checks | Read & Write | Post CI check results | + | Metadata | Read | Required by GitHub | + | Actions | Read | Read workflow run status | + | Deployments | Read & Write | Trigger and track deploys | + | Webhooks | Read | List registered hooks | + +4. Subscribe to events: + - `push` + - `pull_request` + - `pull_request_review` + - `issues` + - `check_run` + - `check_suite` + - `release` + - `workflow_run` + +5. Install the App on the `360magicians`, `pinkycollie`, `MBTQ-dev`, `PinkSync`, and `DeafAUTH` orgs. + +### Generating an Installation Token (per-repo) + +```bash +# 1. Create a JWT signed with the App's private key +APP_ID= +PRIVATE_KEY_PATH=./private-key.pem + +jwt=$(python3 - </access_tokens +# → { "token": "ghs_...", "expires_at": "..." } +``` + +--- + +## Webhook Receiver + +The agent webhook receiver lives at: + +``` +POST https://api.360magicians.com/webhooks/github +``` + +### HMAC Signature Verification + +Every incoming webhook must be verified before processing: + +```typescript +import { createHmac, timingSafeEqual } from 'crypto'; + +function verifyGitHubWebhook( + payload: Buffer, + signature: string, + secret: string +): boolean { + const hmac = createHmac('sha256', secret); + hmac.update(payload); + const digest = Buffer.from(`sha256=${hmac.digest('hex')}`); + const sig = Buffer.from(signature); + if (digest.length !== sig.length) return false; + return timingSafeEqual(digest, sig); +} + +// Express middleware +app.post('/webhooks/github', (req, res) => { + const sig = req.headers['x-hub-signature-256'] as string; + if (!verifyGitHubWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET!)) { + return res.status(401).send('Unauthorized'); + } + // dispatch to handler... +}); +``` + +--- + +## Full Webhook Event Catalog + +### `push` + +| Field | Value | +|-------|-------| +| Trigger | Any push to a watched branch | +| Agent | `ValidatorMagician` (on `develop`), `InfraMagician` (on `main`) | + +```json +{ + "ref": "refs/heads/develop", + "after": "", + "repository": { "full_name": "360magicians/" }, + "pusher": { "name": "DeveloperMagician[bot]" }, + "commits": [{ "message": "feat: ...", "added": [], "modified": [] }] +} +``` + +**Agent action:** Queue lint + type-check jobs; post `check_run` in-progress. + +--- + +### `pull_request.opened` / `pull_request.synchronize` + +| Field | Value | +|-------|-------| +| Trigger | PR opened or new commits pushed to PR branch | +| Agent | `ValidatorMagician` | + +```json +{ + "action": "opened", + "number": 42, + "pull_request": { + "title": "feat(frontend): scaffold Next.js app router", + "head": { "ref": "agent/build-003-frontend", "sha": "" }, + "base": { "ref": "develop" }, + "body": "Closes #15\n\nJob: build-003\nInputs: wireframes.svg" + } +} +``` + +**Agent action:** Run full validation suite; post review comment with `validation_report.json`. + +--- + +### `pull_request_review.submitted` + +| Field | Value | +|-------|-------| +| Trigger | A review is submitted (approved / changes_requested / commented) | +| Agent | `DeveloperMagician` | + +```json +{ + "action": "submitted", + "review": { "state": "approved", "user": { "login": "ValidatorMagician[bot]" } }, + "pull_request": { "number": 42, "mergeable": true } +} +``` + +**Agent action (approved):** Merge PR, delete branch, mark job `completed`, trigger next job. +**Agent action (changes_requested):** Reopen job, post comment with diff instructions. + +--- + +### `issues.opened` — Idea Trigger + +| Field | Value | +|-------|-------| +| Trigger | Issue opened with label `idea` | +| Agent | `IdeaMagician` | + +```json +{ + "action": "opened", + "issue": { + "title": "Deaf-first SaaS for municipal governance", + "body": "Target audience: Deaf community leaders\nTech stack: Next.js + Supabase", + "labels": [{ "name": "idea" }] + } +} +``` + +**Agent action:** Parse `title` + `body` as prompt → `POST /idea` → comment on issue with `idea.json`. + +--- + +### `check_run.completed` + +| Field | Value | +|-------|-------| +| Trigger | A CI check finishes | +| Agent | `InfraMagician` (on success of deploy-check on `main`) | + +```json +{ + "action": "completed", + "check_run": { + "name": "build", + "conclusion": "success", + "head_sha": "", + "check_suite": { "head_branch": "main" } + } +} +``` + +**Agent action:** Trigger `make deploy-all ENV=prod IMAGE_TAG=`. + +--- + +### `release.published` + +| Field | Value | +|-------|-------| +| Trigger | A GitHub Release is published | +| Agent | `OpsMagician` | + +```json +{ + "action": "published", + "release": { + "tag_name": "v1.2.0", + "name": "Release 1.2.0", + "html_url": "https://github.com/360magicians//releases/tag/v1.2.0" + } +} +``` + +**Agent action:** Update monitoring dashboard (`managed-003`); post release notes to Deaf community channels. + +--- + +### `workflow_run.completed` + +| Field | Value | +|-------|-------| +| Trigger | A GitHub Actions workflow finishes | +| Agent | `InfraMagician` | + +```json +{ + "action": "completed", + "workflow_run": { + "name": "CI", + "conclusion": "success", + "head_branch": "main", + "head_sha": "" + } +} +``` + +**Agent action:** Same as `check_run.completed` — deploy to prod if branch is `main`. + +--- + +## API-Level Job Completion Triggers + +When a Magician agent finishes a job it calls the lifecycle API to signal completion: + +``` +POST https://api.360magicians.com/jobs//complete +Authorization: ****** +Content-Type: application/json + +{ + "status": "completed", + "outputs": { + "repository_url": "https://github.com/360magicians/deaf-gov-platform" + } +} +``` + +The API then checks `depends_on` for all jobs that depend on `` and +enqueues them automatically. + +### Job Completion Webhook (outbound) + +The API emits an outbound webhook to any registered subscriber on job status change: + +```json +{ + "event": "job.completed", + "job_id": "build-001", + "stage": "BUILD", + "assigned_to": "DeveloperMagician", + "outputs": { + "repository_url": "https://github.com/360magicians/deaf-gov-platform" + }, + "triggered_jobs": ["build-002", "build-004"], + "timestamp": "2024-01-20T10:30:00Z" +} +``` + +Subscribers register via: + +```bash +curl -X POST https://api.360magicians.com/webhooks/subscribe \ + -H "Authorization: ******" \ + -d '{ + "url": "https://your-listener.example.com/magician-events", + "events": ["job.completed", "job.failed"], + "secret": "" + }' +``` + +--- + +## Prompt Triggers + +### GitHub Issue Label → Agent + +| Label | Agent Triggered | Action | +|-------|----------------|--------| +| `idea` | `IdeaMagician` | Generate idea from issue title/body | +| `validate` | `ValidatorMagician` | Validate linked `idea.json` attachment | +| `research` | `ResearchMagician` | Run market research on issue topic | +| `build` | `DeveloperMagician` | Create repo from issue spec | +| `compliance-check` | `ComplianceMagician` | Generate compliance report | +| `incident` | `OpsMagician` | Open incident tracking and alert | + +### GitHub PR Comment → Agent + +Post a comment beginning with `/magician` to trigger an agent directly: + +| Command | Agent | Action | +|---------|-------|--------| +| `/magician validate` | `ValidatorMagician` | Re-run validation on this PR | +| `/magician review` | `ValidatorMagician` | Post full code review | +| `/magician deploy staging` | `InfraMagician` | Deploy this branch to staging | +| `/magician deploy prod` | `InfraMagician` | Deploy `main` to production | +| `/magician rollback` | `InfraMagician` | Roll back last Helm release | +| `/magician docs` | `DeveloperMagician` | Auto-generate docs for changed files | +| `/magician compliance` | `ComplianceMagician` | Run compliance scan | + +Example: +``` +@360MagiciansBot /magician deploy staging +``` + +### PinkSync Accessibility Event Trigger + +```python +# Any application can emit an accessibility event that triggers PinkSync transforms +import httpx + +httpx.post("https://api.pinksync.io/v1/events", json={ + "app_id": "deaf-gov-platform", + "user_id": "user-12345", + "intent": "visual_only", + "compliance_level": "gold", + "event_type": "page_load", + "metadata": { "route": "/proposals/1" } +}) +``` + +PinkSync responds by emitting transform events to all subscribed downstream services. + +--- + +## Related + +- [Pipeline Handoffs](./pipeline-handoffs.md) +- [Copilot, Bots & Auth Access](./copilot-bots.md) +- [Git Workflow](./git-workflow.md) +- [Environments (dev → prod)](./environments.md) diff --git a/openapi/components/schemas/BuildRepoRequest.yaml b/openapi/components/schemas/BuildRepoRequest.yaml new file mode 100644 index 0000000..023ed50 --- /dev/null +++ b/openapi/components/schemas/BuildRepoRequest.yaml @@ -0,0 +1,18 @@ +type: object +description: Request body for creating a project repository. +required: + - project_name + - project_description +properties: + project_name: + type: string + description: Name of the project / repository. + example: deaf-gov-platform + project_description: + type: string + description: Short description of the project. + example: "Municipal governance platform for Deaf communities" + tech_stack: + type: string + description: Preferred technology stack. + example: "Next.js, TypeScript, Supabase" diff --git a/openapi/components/schemas/CampaignRequest.yaml b/openapi/components/schemas/CampaignRequest.yaml new file mode 100644 index 0000000..8e931c4 --- /dev/null +++ b/openapi/components/schemas/CampaignRequest.yaml @@ -0,0 +1,13 @@ +type: object +description: Request body for running a marketing campaign. +required: + - campaign_brief +properties: + campaign_brief: + type: string + description: Markdown-formatted campaign brief. + example: "# Q1 Campaign\nTarget: Deaf entrepreneurs...\n" + budget: + type: number + description: Optional budget in USD. + example: 5000 diff --git a/openapi/components/schemas/Idea.yaml b/openapi/components/schemas/Idea.yaml new file mode 100644 index 0000000..5d9f6c3 --- /dev/null +++ b/openapi/components/schemas/Idea.yaml @@ -0,0 +1,34 @@ +type: object +description: A generated project idea. +required: + - idea_id + - title + - prompt +properties: + idea_id: + type: string + description: Unique identifier for this idea. + example: idea-abc123 + title: + type: string + description: Short title for the idea. + example: Deaf-First SaaS Platform + prompt: + type: string + description: Original prompt submitted by the user. + example: "Deaf-first SaaS idea for community governance" + description: + type: string + description: Expanded description generated by IdeaMagician. + target_audience: + type: string + description: Primary audience for the idea. + example: Deaf entrepreneurs + tags: + type: array + items: + type: string + example: ["accessibility", "governance", "web3"] + created_at: + type: string + format: date-time diff --git a/openapi/components/schemas/IdeaRequest.yaml b/openapi/components/schemas/IdeaRequest.yaml new file mode 100644 index 0000000..57bd4ae --- /dev/null +++ b/openapi/components/schemas/IdeaRequest.yaml @@ -0,0 +1,13 @@ +type: object +description: Request body for generating an idea. +required: + - prompt +properties: + prompt: + type: string + description: Description of the desired idea. + example: "Deaf-first SaaS idea for municipal governance" + target_audience: + type: string + description: Optional target audience hint. + example: "Deaf entrepreneurs" diff --git a/openapi/components/schemas/Job.yaml b/openapi/components/schemas/Job.yaml new file mode 100644 index 0000000..ae3ba88 --- /dev/null +++ b/openapi/components/schemas/Job.yaml @@ -0,0 +1,40 @@ +type: object +description: A 360 Magicians lifecycle job. +required: + - job_id + - stage + - assigned_to + - status +properties: + job_id: + type: string + description: Unique job identifier. + example: build-003 + stage: + type: string + enum: [IDEA, BUILD, GROW, MANAGED] + description: Lifecycle stage this job belongs to. + example: BUILD + assigned_to: + type: string + description: Magician agent assigned to this job. + example: DeveloperMagician + status: + type: string + enum: [pending, running, completed, failed] + description: Current job status. + example: completed + depends_on: + type: array + description: Job IDs that must complete before this job can start. + items: + type: string + example: ["build-002"] + inputs: + type: object + description: Input parameters for the job. + additionalProperties: true + outputs: + type: object + description: Output artifacts produced by the job. + additionalProperties: true diff --git a/openapi/components/schemas/ResearchRequest.yaml b/openapi/components/schemas/ResearchRequest.yaml new file mode 100644 index 0000000..5de5b7c --- /dev/null +++ b/openapi/components/schemas/ResearchRequest.yaml @@ -0,0 +1,13 @@ +type: object +description: Request body for market research. +required: + - topic +properties: + topic: + type: string + description: Research topic. + example: "Deaf-first SaaS governance market" + target_audience: + type: string + description: Target audience to research. + example: "Deaf entrepreneurs in North America" diff --git a/openapi/components/schemas/ValidationReport.yaml b/openapi/components/schemas/ValidationReport.yaml new file mode 100644 index 0000000..4737426 --- /dev/null +++ b/openapi/components/schemas/ValidationReport.yaml @@ -0,0 +1,36 @@ +type: object +description: Validation report produced by ValidatorMagician. +required: + - idea_id + - is_valid +properties: + idea_id: + type: string + description: ID of the validated idea. + example: idea-abc123 + is_valid: + type: boolean + description: Whether the idea passed validation. + compliance_score: + type: number + format: float + minimum: 0 + maximum: 100 + description: Compliance score out of 100. + example: 87.5 + feasibility_score: + type: number + format: float + minimum: 0 + maximum: 100 + description: Feasibility score out of 100. + example: 92.0 + issues: + type: array + description: List of validation issues found. + items: + type: string + example: [] + notes: + type: string + description: Additional notes from ValidatorMagician. diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 7e231f6..c9085d9 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,122 +1,574 @@ openapi: 3.1.0 info: version: 1.0.0 - title: Example API - termsOfService: https://example.com/terms/ + title: 360 Magicians API + termsOfService: https://360magicians.com/terms/ contact: - name: Contact our support - email: contact@example.com - url: http://example.com/contact + name: 360 Magicians Support + url: https://360magicians.com/contact license: - name: Apache 2.0 - url: http://www.apache.org/licenses/LICENSE-2.0.html + name: MIT + url: https://opensource.org/licenses/MIT x-logo: url: 'https://redocly.github.io/openapi-template/logo.png' - altText: OpenAPI example logo + altText: 360 Magicians logo description: > - This is an **example** API to demonstrate features of the OpenAPI - specification. + # 360 Magicians API - # Introduction + **Deaf Aware. Rooted Deaf First. Globally Future-Proof AIs.** - This API definition is intended to to be a good starting point for - describing your API in [OpenAPI/Swagger - format](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md). - It also demonstrates features of the - [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool - and the [Redoc](https://github.com/Redocly/Redoc) documentation engine. Beyond - the standard OpenAPI syntax, we use a few - [vendor extensions](https://github.com/Redocly/Redoc/blob/main/docs/redoc-vendor-extensions.md). + The 360 Magicians API powers the **IDEA → BUILD → GROW → MANAGED** lifecycle for Deaf-first + AI projects. All endpoints are authenticated via **DeafAUTH** bearer tokens. - # OpenAPI Specification - The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which - allows both humans and computers to discover and understand the capabilities - of the service without access to source - code, documentation, or through network traffic inspection. When properly - defined via OpenAPI, a consumer can - understand and interact with the remote service with a minimal amount of - implementation logic. Similar to what - interfaces have done for lower-level programming, OpenAPI removes the - guesswork in calling the service. + ## Authentication + + Obtain a token from [DeafAUTH](https://deafauth.mbtq.dev/docs) and pass it as a ****** + + ``` + Authorization: ****** + ``` + + + ## Lifecycle Stages + + | Stage | Description | + |---------|-------------| + | **IDEA** | Generate, validate, and research ideas | + | **BUILD** | Create repos, wireframes, and deploy MVPs | + | **GROW** | Analytics, marketing campaigns, partner onboarding | + | **MANAGED** | Compliance, finance, and continuous monitoring | + + + ## Related Docs + + - [About 360Magicians](../docs/about.md) + - [Infrastructure / Ecosystem Architecture](../docs/infrastructure.md) + - [DeafAuth](../docs/projects/deafauth.md) + - [PinkSync](../docs/projects/pinksync.md) + - [Municipal DAO](../docs/projects/municipal-dao.md) externalDocs: - description: "Find out how to create a GitHub repo for your OpenAPI definition." - url: 'https://github.com/Redocly/create-openapi-repo' + description: "360 Magicians ecosystem documentation" + url: 'https://github.com/360magicians' tags: - - name: Echo - description: "Example echo operations." - - name: User - description: "Example actions on user accounts." - - name: Admin - description: "Example operations reserved for administrators." - - name: Info - description: "Example operations for retrieving information." - - name: Tag - description: "This is a tag description." + - name: Auth + description: "DeafAUTH identity and token operations." + - name: Idea + description: "IDEA stage — generate, validate, and research ideas." + - name: Build + description: "BUILD stage — repo creation, wireframes, and MVP deployment." + - name: Grow + description: "GROW stage — analytics, marketing, and partner onboarding." + - name: Managed + description: "MANAGED stage — compliance, finance, and monitoring." + - name: Jobs + description: "Job listing and status across all lifecycle stages." + - name: Inference + description: "AI inference endpoints — LLM, VLM, embeddings, and ASR." x-tagGroups: - - name: General + - name: Identity + tags: + - Auth + - name: Lifecycle tags: - - User - - Info - - Echo - - name: Administration + - Jobs + - Idea + - Build + - Grow + - Managed + - name: AI Inference tags: - - Admin + - Inference servers: - - url: https://{tenant}/api/v1 - variables: - tenant: - default: www - description: Your tenant id - - url: https://example.com/api/v1 + - url: https://api.360magicians.com + description: Production API paths: - '/users/{username}': - $ref: 'paths/users_{username}.yaml' - '/user': - $ref: 'paths/user.yaml' - '/user/list': - $ref: 'paths/user-status.yaml' - /pathItem: - $ref: paths/pathItem.yaml - /pathItemWithExamples: - $ref: paths/pathItemWithExamples.yaml - '/echo': - $ref: 'paths/echo.yaml' -components: - securitySchemes: - main_auth: - description: "Example description text of the OAuth2 scheme." - type: oauth2 - flows: - implicit: - authorizationUrl: http://example.com/api/oauth/dialog - scopes: - 'read:users': read user info - 'write:users': modify or remove users - api_key: - description: "Example description text of the API key scheme." - type: apiKey - in: header - name: api_key - basic_auth: - type: http - scheme: basic -webhooks: - userInfo: + '/jobs/list': + get: + tags: + - Jobs + summary: List all jobs + operationId: listJobs + description: Returns all jobs across the IDEA, BUILD, GROW, and MANAGED lifecycle stages. + security: + - deafauth: [] + responses: + '200': + description: A list of lifecycle jobs. + content: + application/json: + schema: + type: array + items: + $ref: 'components/schemas/Job.yaml' + '401': + description: Unauthorized — invalid or missing DeafAUTH token. + '/idea': + post: + tags: + - Idea + summary: Generate an idea + operationId: generateIdea + description: | + Submit a prompt to IdeaMagician to generate a new Deaf-first project idea. + Returns an `idea.json` payload. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: 'components/schemas/IdeaRequest.yaml' + responses: + '200': + description: Idea generated successfully. + content: + application/json: + schema: + $ref: 'components/schemas/Idea.yaml' + '401': + description: Unauthorized. + '/idea/validate': + post: + tags: + - Idea + summary: Validate an idea + operationId: validateIdea + description: | + Submit an `idea.json` to ValidatorMagician for compliance and feasibility validation. + Returns a `validation_report.json`. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: 'components/schemas/Idea.yaml' + responses: + '200': + description: Validation report. + content: + application/json: + schema: + $ref: 'components/schemas/ValidationReport.yaml' + '401': + description: Unauthorized. + '/idea/research': + post: + tags: + - Idea + summary: Run market research + operationId: researchIdea + description: | + Submit a topic and target audience to ResearchMagician. + Returns a `market_research_report.md`. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: 'components/schemas/ResearchRequest.yaml' + responses: + '200': + description: Market research report (Markdown). + content: + text/markdown: + schema: + type: string + '401': + description: Unauthorized. + '/build/repo': + post: + tags: + - Build + summary: Create project repository + operationId: createRepo + description: | + Instruct DeveloperMagician to create a new GitHub repository for a project. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: 'components/schemas/BuildRepoRequest.yaml' + responses: + '201': + description: Repository created. + content: + application/json: + schema: + type: object + properties: + repository_url: + type: string + format: uri + '401': + description: Unauthorized. + '/grow/campaign': post: - summary: New user webhook - description: "Information about a new user in the system." - operationId: userInfo tags: - - Info + - Grow + summary: Run marketing campaign + operationId: runCampaign + description: | + Submit a campaign brief to GrowthMagician to execute a marketing campaign. + security: + - deafauth: [] requestBody: + required: true content: application/json: schema: - $ref: 'components/schemas/User.yaml' + $ref: 'components/schemas/CampaignRequest.yaml' responses: '200': - description: "Successfully retrieved information about a new user." + description: Campaign report. + content: + text/markdown: + schema: + type: string + '401': + description: Unauthorized. + '/managed/compliance': + post: + tags: + - Managed + summary: Generate compliance report + operationId: generateComplianceReport + description: | + Instruct ComplianceMagician to generate a compliance report for a given period. security: - - api_key: [] + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reporting_period] + properties: + reporting_period: + type: string + description: ISO 8601 date range, e.g. "2024-Q1" + example: "2024-Q1" + responses: + '200': + description: Compliance report (PDF URL). + content: + application/json: + schema: + type: object + properties: + report_url: + type: string + format: uri + '401': + description: Unauthorized. + '/inference/llm': + post: + tags: + - Inference + summary: LLM text generation + operationId: inferLLM + description: | + Submit a text prompt to the inference gateway. The gateway routes to the appropriate + provider (Vertex AI, OpenAI, Anthropic, Groq, HuggingFace, or local Ollama) based + on the `model` field. Supports streaming via SSE when `stream: true`. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InferLLMRequest' + responses: + '200': + description: | + Generated text response. If `stream` is `true`, returns a `text/event-stream` + (SSE) response; otherwise returns JSON. + content: + application/json: + schema: + $ref: '#/components/schemas/InferLLMResponse' + text/event-stream: + schema: + type: string + description: Server-Sent Events stream of text delta chunks. + '401': + description: Unauthorized. + '422': + description: Invalid request (unknown model, missing prompt). + '503': + description: All inference providers in the fallback chain are unavailable. + '/inference/vlm': + post: + tags: + - Inference + summary: VLM vision + text generation + operationId: inferVLM + description: | + Submit a prompt and one or more image URLs to a vision-language model (VLM). + Supports multimodal inputs for sign-language frame analysis, accessibility + description, and visual content understanding. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InferVLMRequest' + responses: + '200': + description: VLM text response. + content: + application/json: + schema: + $ref: '#/components/schemas/InferLLMResponse' + '401': + description: Unauthorized. + '422': + description: Invalid request. + '/inference/embed': + post: + tags: + - Inference + summary: Text embedding + operationId: inferEmbed + description: | + Generate dense vector embeddings for one or more input strings. + Used for semantic search, RAG retrieval, and accessibility preference matching. + security: + - deafauth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InferEmbedRequest' + responses: + '200': + description: Embedding vectors. + content: + application/json: + schema: + $ref: '#/components/schemas/InferEmbedResponse' + '401': + description: Unauthorized. + '422': + description: Invalid request. + '/inference/asr': + post: + tags: + - Inference + summary: Automatic speech recognition (ASR) + operationId: inferASR + description: | + Transcribe audio input to text using Whisper or an equivalent ASR model. + Supports Deaf-first audio pipelines, live caption generation, and sign-language + companion transcription. + security: + - deafauth: [] + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/InferASRRequest' + responses: + '200': + description: Transcription result. + content: + application/json: + schema: + $ref: '#/components/schemas/InferASRResponse' + '401': + description: Unauthorized. + '422': + description: Invalid request (unsupported audio format). +components: + securitySchemes: + deafauth: + type: http + scheme: bearer + bearerFormat: JWT + description: "DeafAUTH bearer token. Obtain from https://deafauth.mbtq.dev/docs" + schemas: + Job: + $ref: 'components/schemas/Job.yaml' + Idea: + $ref: 'components/schemas/Idea.yaml' + InferLLMRequest: + type: object + required: [model, prompt] + properties: + model: + type: string + description: | + Model identifier. Use provider-prefixed slugs: + `gemini-1.5-pro`, `gpt-4o`, `claude-3-5-sonnet`, `groq/llama3-70b`, + `hf/mistralai/Mistral-7B-Instruct-v0.3`, `local/llama3`. + example: "gemini-1.5-pro" + prompt: + type: string + description: User prompt / instruction. + example: "Summarize the Deaf-first design principles." + system: + type: string + description: Optional system prompt. + stream: + type: boolean + default: false + description: If true, response is streamed as SSE. + max_tokens: + type: integer + minimum: 1 + maximum: 32768 + description: Maximum tokens in the response. + temperature: + type: number + minimum: 0 + maximum: 2 + description: Sampling temperature. + capabilities: + type: array + items: + type: string + enum: [text-gen, code-gen] + description: Required capability tags used for model routing validation. + InferLLMResponse: + type: object + properties: + model: + type: string + description: Actual model used (may differ from requested if fallback occurred). + provider: + type: string + description: Inference provider used (e.g. "vertex-ai", "openai", "groq", "hf"). + text: + type: string + description: Generated text output. + finish_reason: + type: string + enum: [stop, length, content_filter, error] + usage: + type: object + properties: + prompt_tokens: + type: integer + completion_tokens: + type: integer + total_tokens: + type: integer + InferVLMRequest: + type: object + required: [model, prompt, images] + properties: + model: + type: string + description: VLM model identifier (must support vision capability). + example: "gpt-4o" + prompt: + type: string + description: Text prompt to accompany the images. + images: + type: array + items: + type: string + format: uri + description: One or more image URLs to include in the request. + minItems: 1 + maxItems: 10 + stream: + type: boolean + default: false + capabilities: + type: array + items: + type: string + enum: [vision, asl-sign] + description: Required capability tags (e.g. `asl-sign` for sign-language frames). + InferEmbedRequest: + type: object + required: [model, input] + properties: + model: + type: string + description: Embedding model identifier. + example: "hf/BAAI/bge-large-en-v1.5" + input: + oneOf: + - type: string + - type: array + items: + type: string + description: Text string or array of strings to embed. + InferEmbedResponse: + type: object + properties: + model: + type: string + provider: + type: string + embeddings: + type: array + items: + type: array + items: + type: number + description: Array of embedding vectors (one per input string). + dimensions: + type: integer + description: Dimensionality of each embedding vector. + InferASRRequest: + type: object + required: [audio] + properties: + audio: + type: string + format: binary + description: Audio file (wav, mp3, m4a, ogg, flac). Max 25 MB. + model: + type: string + default: "openai/whisper-large-v3" + description: ASR model identifier. + language: + type: string + description: BCP-47 language code hint (e.g. "en", "asl"). Optional. + task: + type: string + enum: [transcribe, translate] + default: transcribe + InferASRResponse: + type: object + properties: + model: + type: string + provider: + type: string + text: + type: string + description: Full transcription text. + language: + type: string + description: Detected language code. + segments: + type: array + description: Word/segment-level timestamps (if available). + items: + type: object + properties: + start: + type: number + end: + type: number + text: + type: string diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..1f032a4 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,29 @@ +{ + "name": "acme-api", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "acme-api", + "version": "1.0.0", + "dependencies": { + "@redocly/cli": "2.34.0" + } + }, + "node_modules/@redocly/cli": { + "version": "2.34.0", + "resolved": "https://registry.npmjs.org/@redocly/cli/-/cli-2.34.0.tgz", + "integrity": "sha512-wlEy03fyf+xrEatHbSSLFGP7T8slYwyJHO6xooArvUOntiGRMPuTGivaSPhxx+f2bFhe69zDDzDy51+CsvJ/zw==", + "license": "MIT", + "bin": { + "openapi": "bin/cli.js", + "redocly": "bin/cli.js" + }, + "engines": { + "node": ">=22.12.0 || >=20.19.0 <21.0.0", + "npm": ">=10" + } + } + } +} diff --git a/redocly.yaml b/redocly.yaml index 999bf72..d4a7aeb 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -1,6 +1,6 @@ # See https://redocly.com/docs/cli/configuration/ for more information. apis: - sample@v1: + 360magicians@v1: root: openapi/openapi.yaml extends: - recommended