{"slug":"architecture","title":"System Architecture","description":"Technical architecture of the Polymaths platform","lastUpdated":"2026-03-06","category":"technical","content":"# Polymaths Architecture\n\n> Technical architecture for the Polymaths resource platform\n> Part of the Platphorm News Network\n\n---\n\n## System Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    POLYMATHS.PLATPHORMNEWS.COM                      │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │\n│  │   Next.js   │  │   AI SDK    │  │  Platphorm  │                 │\n│  │  App Router │  │   Vercel    │  │   Network   │                 │\n│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                 │\n│         │                │                │                         │\n│  ┌──────┴────────────────┴────────────────┴──────┐                 │\n│  │              Unified API Layer                 │                 │\n│  │         /api/v1/* | /api/mcp | /api/*         │                 │\n│  └──────────────────────┬────────────────────────┘                 │\n│                         │                                           │\n│  ┌──────────────────────┴────────────────────────┐                 │\n│  │              Content & Data Layer              │                 │\n│  │   Static JSON | Markdown Docs | API Routes    │                 │\n│  └───────────────────────────────────────────────┘                 │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────────┐\n│                   PLATPHORM NEWS NETWORK                            │\n├─────────────────────────────────────────────────────────────────────┤\n│  mcp.platphormnews.com    │  MCP Hub & Registry                    │\n│  monitor.platphormnews.com│  Network Health Dashboard              │\n│  jobs.platphormnews.com   │  Career Platform                       │\n│  atlas.platphormnews.com  │  Geographic Data                       │\n│  desa.platphormnews.com   │  Analytics Platform                    │\n│  ...84+ federated sites   │                                        │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Technology Stack\n\n### Core Framework\n| Layer | Technology | Version | Purpose |\n|-------|-----------|---------|---------|\n| Runtime | Node.js | 20+ | Server runtime |\n| Framework | Next.js | 16 | App Router, RSC, API |\n| Language | TypeScript | 5.x | Type safety |\n| Styling | Tailwind CSS | 4.x | Utility-first CSS |\n| Components | shadcn/ui | Latest | UI primitives |\n\n### AI & ML\n| Component | Technology | Purpose |\n|-----------|-----------|---------|\n| AI Gateway | Vercel AI Gateway | Model routing |\n| AI SDK | AI SDK 6.x | Chat, streaming, tools |\n| Default Model | openai/gpt-4o-mini | Cost-effective reasoning |\n\n### Integration\n| System | Protocol | Purpose |\n|--------|----------|---------|\n| Platphorm Network | REST + MCP | Federated services |\n| MCP Hub | JSON-RPC 2.0 | Tool orchestration |\n| Analytics | Vercel Analytics | Usage tracking |\n\n---\n\n## Directory Structure\n\n```\npolymaths.platphormnews.com/\n├── app/\n│   ├── (pages)/                    # Route groups\n│   │   ├── page.tsx                # Landing page\n│   │   ├── learn/page.tsx          # Learning resources\n│   │   ├── polymaths/page.tsx      # Polymath directory\n│   │   ├── resources/page.tsx      # Curated resources\n│   │   └── about/page.tsx          # About & mission\n│   │\n│   ├── api/\n│   │   ├── health/route.ts         # Health check\n│   │   ├── docs/page.tsx           # API documentation\n│   │   ├── mcp/route.ts            # MCP endpoint\n│   │   ├── mentor/chat/route.ts    # AI mentor\n│   │   └── v1/\n│   │       ├── polymaths/          # Polymath data\n│   │       ├── principles/         # Principles data\n│   │       ├── quotes/             # Quotes API\n│   │       ├── docs/               # Documentation API\n│   │       └── network/            # Network integration\n│   │\n│   ├── sitemap.ts                  # Dynamic sitemap\n│   ├── robots.ts                   # Robots.txt\n│   ├── rss.xml/route.ts            # RSS feed\n│   ├── feed.xml/route.ts           # Atom feed\n│   ├── llms.txt/route.ts           # LLM discovery\n│   ├── llms-full.txt/route.ts      # Full LLM context\n│   └── llms-index.json/route.ts    # Structured LLM index\n│\n├── components/\n│   ├── sections/                   # Page sections (e.g., FAQ, Hero)\n│   ├── ui/                         # shadcn components\n│   ├── polymath-mentor.tsx         # AI chat interface\n│   ├── knowledge-graph.tsx         # Interactive viz\n│   ├── vitruvian-animation.tsx     # Hero animation\n│   └── ...\n│\n├── docs/\n│   ├── PRINCIPLES.md               # Core philosophy\n│   ├── ARCHITECTURE.md             # This document\n│   ├── ROADMAP.md                  # Development roadmap\n│   ├── STANDARDS.md                # Code standards\n│   ├── GOALS.md                    # Project goals\n│   └── INTEGRATION.md              # Network integration\n│\n├── lib/\n│   ├── data/                       # Static data\n│   │   ├── polymaths.ts            # Polymath profiles\n│   │   ├── principles.ts           # Principles data\n│   │   └── quotes.ts               # Quote collection\n│   └── utils.ts                    # Utilities\n│\n├── public/\n│   ├── icon.svg                    # Logo\n│   ├── og-image.jpg                # Social image\n│   ├── manifest.json               # PWA manifest\n│   └── robots.txt                  # Robots file\n│\n└── hooks/\n    ├── use-scroll-animation.ts     # Scroll animations\n    └── ...\n```\n\n---\n\n## API Architecture\n\n### REST API (v1)\n\nBase URL: `https://polymaths.platphormnews.com/api/v1`\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/polymaths` | GET | List all polymaths |\n| `/polymaths/:slug` | GET | Get polymath by slug |\n| `/principles` | GET | List all principles |\n| `/quotes` | GET | Get random quotes |\n| `/quotes?author=:name` | GET | Filter by author |\n| `/docs/:filename` | GET | Get documentation |\n| `/network/sites` | GET | Network sites |\n| `/network/status` | GET | Network health |\n\n### Response Format\n\n```typescript\ninterface APIResponse<T> {\n  success: boolean;\n  data: T;\n  meta: {\n    version: string;\n    timestamp: string;\n    requestId: string;\n  };\n  pagination?: {\n    page: number;\n    limit: number;\n    total: number;\n    hasMore: boolean;\n  };\n}\n```\n\n### Error Format\n\n```typescript\ninterface APIError {\n  success: false;\n  error: {\n    code: string;\n    message: string;\n    details?: Record<string, unknown>;\n  };\n  meta: {\n    version: string;\n    timestamp: string;\n    requestId: string;\n  };\n}\n```\n\n---\n\n## MCP Integration\n\n### Endpoint\n\n`POST https://polymaths.platphormnews.com/api/mcp`\n\n### Protocol\n\nJSON-RPC 2.0 compliant\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_polymath` | Get polymath profile |\n| `list_polymaths` | List all polymaths |\n| `get_principles` | Get polymath principles |\n| `get_random_quote` | Get inspiring quote |\n| `search_content` | Search all content |\n\n### Example Request\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_polymath\",\n    \"arguments\": {\n      \"slug\": \"leonardo-da-vinci\"\n    }\n  },\n  \"id\": 1\n}\n```\n\n---\n\n## Data Models\n\n### Polymath\n\n```typescript\ninterface Polymath {\n  id: string;\n  slug: string;\n  name: string;\n  lifespan: string;\n  era: string;\n  nationality: string;\n  portrait?: string;\n  disciplines: string[];\n  achievements: string[];\n  quotes: string[];\n  principles: string[];\n  works: Work[];\n  connections: Connection[];\n  metadata: {\n    createdAt: string;\n    updatedAt: string;\n    version: number;\n  };\n}\n```\n\n### Principle\n\n```typescript\ninterface Principle {\n  id: string;\n  slug: string;\n  name: string;\n  description: string;\n  practices: string[];\n  relatedPolymaths: string[];\n  resources: Resource[];\n}\n```\n\n---\n\n## SEO Architecture\n\n### Meta Strategy\n\n```typescript\n// Per-page metadata generation\nexport async function generateMetadata({ params }): Promise<Metadata> {\n  return {\n    title: '...',\n    description: '...',\n    openGraph: { ... },\n    twitter: { ... },\n    alternates: { canonical: '...' },\n  };\n}\n```\n\n### Structured Data\n\n| Type | Pages |\n|------|-------|\n| Organization | All pages |\n| WebSite | Homepage |\n| FAQPage | FAQ sections |\n| Article | Content pages |\n| Person | Polymath profiles |\n| Course | Learning paths |\n| BreadcrumbList | All pages |\n\n### Sitemap Structure\n\n```\n/sitemap.xml (index)\n├── /sitemap-pages.xml      # Static pages\n├── /sitemap-polymaths.xml  # Polymath profiles\n├── /sitemap-resources.xml  # Resources\n└── /sitemap-docs.xml       # Documentation\n```\n\n---\n\n## Performance Targets\n\n| Metric | Target | Measurement |\n|--------|--------|-------------|\n| LCP | < 2.5s | Largest Contentful Paint |\n| FID | < 100ms | First Input Delay |\n| CLS | < 0.1 | Cumulative Layout Shift |\n| TTFB | < 200ms | Time to First Byte |\n| TTI | < 3.5s | Time to Interactive |\n\n### Optimization Strategies\n\n1. **Static Generation**: Pre-render all content pages\n2. **Image Optimization**: Next.js Image with blur placeholders\n3. **Code Splitting**: Dynamic imports for heavy components\n4. **Edge Caching**: Vercel Edge Network\n5. **Font Optimization**: next/font with display swap\n\n---\n\n## Security\n\n### Headers\n\n```typescript\n// next.config.js\nheaders: [\n  {\n    key: 'X-Frame-Options',\n    value: 'DENY',\n  },\n  {\n    key: 'X-Content-Type-Options',\n    value: 'nosniff',\n  },\n  {\n    key: 'Referrer-Policy',\n    value: 'strict-origin-when-cross-origin',\n  },\n  {\n    key: 'Content-Security-Policy',\n    value: \"default-src 'self'; ...\",\n  },\n]\n```\n\n### Rate Limiting\n\n| Endpoint | Limit | Window |\n|----------|-------|--------|\n| `/api/v1/*` | 100 | 1 minute |\n| `/api/mentor/chat` | 20 | 1 minute |\n| `/api/mcp` | 50 | 1 minute |\n\n---\n\n## Deployment\n\n### Infrastructure\n\n| Service | Provider | Purpose |\n|---------|----------|---------|\n| Hosting | Vercel | Edge deployment |\n| DNS | Cloudflare | DNS management |\n| Analytics | Vercel Analytics | Usage metrics |\n| Monitoring | Vercel | Error tracking |\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `NEXT_PUBLIC_SITE_URL` | Yes | Site URL |\n| `PLATPHORM_API_KEY` | No | Network API key |\n\n---\n\n## Monitoring & Observability\n\n### Health Check\n\n`GET /api/health`\n\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"1.0.0\",\n  \"timestamp\": \"2026-03-06T12:00:00Z\",\n  \"checks\": {\n    \"api\": \"ok\",\n    \"network\": \"ok\"\n  }\n}\n```\n\n### Logging\n\nStructured JSON logging with:\n- Request ID\n- User agent\n- Route\n- Latency\n- Status code\n\n---\n\n*Document Version: 1.0.0*\n*Last Updated: March 2026*\n*Part of the Platphorm News Network*\n","url":"https://polymaths.platphormnews.com/docs/architecture","apiUrl":"https://polymaths.platphormnews.com/api/v1/docs/architecture","formats":{"json":"/api/v1/docs/architecture","markdown":"/api/v1/docs/architecture?format=markdown"}}