Sankofa/docs/architecture-root/ENTERPRISE_ARCHITECTURE.md

Enterprise-Class Web Presence Architecture

This document outlines the three-layer enterprise-class web presence architecture for Sankofa's Phoenix Nexus Cloud, modeled after Microsoft's proven enterprise pattern.

Overview

The web presence is organized into three distinct layers, each serving a specific purpose while maintaining unified identity and design:

1. Public Marketing Sites - Customer-facing marketing and information
2. Docs & Learning Hubs - Technical documentation and training
3. Signed-In Portals - Role-based administrative and operational interfaces

---

Layer 1: Public Marketing Sites

Purpose: Customer acquisition, brand awareness, product information, and trust building.

URLs:

• Main site: https://sankofa.nexus (or https://sankofa.nexus)
• Product pages: https://sankofa.nexus/products/*
• Solutions: https://sankofa.nexus/solutions/*

Navigation Structure

The main navigation follows Microsoft's pattern with clear audience segmentation:

Products / Platform
├── All Products
├── Compute
├── Storage
├── Networking
└── AI & Machine Learning

Solutions
├── Enterprise
├── Government
├── Institutional
└── Sovereignty & Compliance

Developers
Partners
Company
├── About
├── Manifesto
├── Trust & Compliance
└── Security

Support

Key Features

• Audience Segmentation: Clear entry points for Individuals, Business, Enterprise, Government, Developers, Partners
• Outcome-Oriented Messaging: Focus on business outcomes, not just features
• Persistent Sign-In: "Sign In" button in header routes to appropriate portal based on user role
• Trust & Compliance: Easily accessible security, compliance, and accessibility content
• Global-Ready: Language switchers and region targeting (future)

Pages

• / - Homepage with hero, features, and CTAs
• /products - Product catalog
• /solutions/enterprise - Enterprise solutions landing
• /solutions/government - Government solutions landing
• /solutions/institutional - Institutional solutions landing
• /developers - Developer resources hub
• /partners - Partner program information
• /company/trust - Trust, security, and compliance
• /company/security - Security details
• /support - Support center

---

Layer 2: Signed-In Portals

Purpose: Operational interfaces for managing infrastructure, users, and resources.

Portal Structure

1. Nexus Console (Operational View)

URL: https://nexus.sankofa.nexus or https://portal.sankofa.nexus

Purpose: Technical operations, integrations, data pipelines, system health

Features:

• Role-based dashboards (Technical Admin, System Operator, etc.)
• Search-first UX for deep configurations
• Task-oriented navigation ("Add Integration", "Create Connection", "View Logs")
• In-context help linking to Sankofa docs
• Real-time monitoring and alerts

Access: Technical admins, system operators, DevOps engineers

2. Customer / Tenant Admin Portal

URL: https://admin.sankofa.nexus

Purpose: Manage organizations, users, permissions, billing

Features:

• Organization management
• User and role management
• Permission configuration
• Billing and subscription management
• Usage analytics and reporting
• Budget management and alerts

Access: Business owners, organization admins, billing admins

3. Developer Portal

URL: https://developers.sankofa.nexus

Purpose: API keys, documentation, test environments, logs

Features:

• API key management
• Test environment provisioning
• API usage analytics
• Log viewer
• SDK downloads
• Integration guides

Access: Developers, API consumers

4. Partner Portal

URL: https://partners.sankofa.nexus

Purpose: Co-sell deals, technical onboarding, solution registration

Features:

• Deal registration
• Technical onboarding workflows
• Solution marketplace listing
• Partner resources and enablement
• Co-marketing materials

Access: Partners, solution providers

Portal Characteristics

All portals share these enterprise-class characteristics:

1. Role-Based Dashboards

   • Different capabilities visible based on user role
   • Customizable tile layouts
   • Quick actions for common tasks

2. Task-Oriented Navigation

   • Primary actions exposed prominently
   • Contextual menus
   • Breadcrumb navigation

3. Search-First UX

   • Global search bar
   • Search across resources, settings, docs
   • Keyboard shortcuts

4. Contextual Help & Learning

   • Right rail or tiles with relevant docs
   • In-context tutorials
   • Links to training materials

5. Consistent Design Language

   • Unified component library
   • Same typography, spacing, colors
   • Shared navigation patterns

---

Layer 3: Docs & Learning Hub

Purpose: Technical documentation, API references, tutorials, and learning resources.

URL: https://docs.sankofa.nexus or https://learn.sankofa.nexus

Structure

Documentation Hub
├── Getting Started
│   ├── Quick Start Guides
│   ├── Installation
│   └── First Steps
├── API Reference
│   ├── GraphQL API
│   ├── REST APIs
│   └── WebSocket APIs
├── Guides
│   ├── Architecture Guides
│   ├── Security Guides
│   ├── Compliance Guides
│   └── Best Practices
├── Tutorials
│   ├── Step-by-Step Tutorials
│   ├── Use Cases
│   └── Examples
├── SDKs & Tools
│   ├── CLI Documentation
│   ├── SDK References
│   └── Terraform Provider
└── Governance
    ├── Architecture Blueprints
    ├── RMF Documentation
    └── Compliance Templates

Integration Points

• Links from public site (Developers / Docs)
• Links from Nexus Console (Help / Docs)
• Links from Developer Portal (Documentation)
• Links from Partner Portal (Enablement)
• Contextual links from portals (matching current screen)

Features

• Search: Full-text search across all documentation
• Versioning: Multiple versions of docs for different API versions
• Interactive Examples: Code examples with "Try it" functionality
• Video Tutorials: Embedded video content
• Community: Forums, Q&A, and community contributions

---

Cross-Cutting Traits

1. Unified Identity & Design

• Same Logo: Consistent branding across all layers
• Typography: Shared font families and hierarchy
• Color System: Unified color palette (Phoenix Fire, Sankofa Gold, etc.)
• Component Library: Shared UI components across portals
• Spacing System: Consistent spacing and layout patterns

2. Deep Sign-In Integration

• Single Sign-On (SSO): Keycloak-based authentication
• Smooth Flow: Seamless transition from public site to portals
• Role Detection: Automatic routing to appropriate portal based on user role
• Session Management: Persistent sessions across portals

3. Performance & Responsiveness

• Fast Load Times: Optimized for performance
• Responsive Design: Works on all devices
• Progressive Enhancement: Core functionality works without JavaScript
• CDN Distribution: Global content delivery

4. Security, Privacy, and Compliance

• Trust Center: Dedicated trust/compliance content
• Security Statements: Clear security documentation
• Privacy Policy: Transparent data handling
• Compliance Certifications: Visible compliance badges

5. Global & Accessibility

• Multi-Language: Support for multiple languages (future)
• Region Targeting: Content tailored per region (future)
• Accessibility: WCAG 2.1 AA compliance
• Internationalization: Ready for global expansion

---

Implementation Status

✅ Completed

• Enhanced public site navigation with enterprise-class structure
• Created Enterprise solutions landing page
• Created Developers hub page
• Created Trust & Compliance page
• Added persistent Sign In link in header
• Portal structure exists (portal/ directory)

🚧 In Progress

• Complete all public site pages (Partners, Support, etc.)
• Enhance Nexus Console with role-based dashboards
• Create Customer/Tenant Admin Portal
• Create Developer Portal
• Create Partner Portal
• Build centralized Docs & Learning hub
• Implement SSO flow between public site and portals
• Unified design system documentation

📋 Planned

• Global language support
• Region targeting
• Advanced search across all layers
• Analytics and tracking
• A/B testing framework

---

Technical Architecture

Public Site

• Framework: Next.js 14+ (App Router)
• Styling: Tailwind CSS + shadcn/ui
• Hosting: Phoenix infrastructure
• Domain: sankofa.nexus or sankofa.nexus

Portals

• Framework: Next.js 14+ (App Router)
• Authentication: Keycloak OIDC
• State Management: TanStack Query
• Styling: Shared component library
• Hosting: Phoenix infrastructure
• Domains: nexus.sankofa.nexus, admin.sankofa.nexus, etc.

Docs Hub

• Framework: Next.js 14+ or dedicated docs framework (Docusaurus, etc.)
• Content: Markdown with MDX support
• Search: Full-text search (Algolia, etc.)
• Hosting: Phoenix infrastructure
• Domain: docs.sankofa.nexus or learn.sankofa.nexus

---

References

• Microsoft's enterprise web presence pattern
• Azure Portal design patterns
• Microsoft 365 Admin Center UX
• Microsoft Learn documentation structure

---

Next Steps

1. Complete remaining public site pages
2. Enhance portal dashboards with role-based views
3. Build out Developer Portal
4. Create centralized documentation hub
5. Implement unified design system
6. Set up SSO flow between layers