# 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

- [x] Enhanced public site navigation with enterprise-class structure
- [x] Created Enterprise solutions landing page
- [x] Created Developers hub page
- [x] Created Trust & Compliance page
- [x] Added persistent Sign In link in header
- [x] 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