Sankofa/README.md

# Sankofa

**Sovereign authority governing identity, policy, and ecosystem structure.**

## Overview

**Sankofa Ltd** serves as the technical nexus for all system operations and integrations, functioning as the central hub for infrastructure, data exchange, and platform orchestration. All computing resources, hosting environments, and cloud-based services that support Sankofa's technical operations are powered by **Phoenix**, which acts as the dedicated cloud service provider. ([Reference: https://sankofa.nexus](https://sankofa.nexus))

**Sankofa** is the parent ecosystem brand, and **Sankofa Phoenix** is the sovereign cloud platform that powers the ecosystem.

## Joint Ventures

### PanTel
**Sankofa** is a joint venture partner in **PanTel**, a telecommunications infrastructure project with **PANDA** (Pan-African Network for Digital Advancement). PanTel combines Sankofa's cloud infrastructure capabilities with PANDA's digital advancement network to deliver telecommunications and connectivity services, including 6G/GPU infrastructure.

**Sankofa Phoenix** is a next-generation, sovereign AI cloud infrastructure platform that combines:

- **Mythic Power**: Phoenix transformation and rebirth
- **Ancestral Wisdom**: Sankofa memory and return
- **Cultural Identity**: Akan heritage and sovereignty
- **Global Reach**: 325-region deployment
- **Technical Excellence**: World-class cloud infrastructure
- **Multi-Tenancy**: Advanced tenant isolation and billing (Superior to Azure)
- **Sovereign Identity**: Keycloak-based identity management (NO Azure dependencies)

## Tech Stack

### Frontend
- **Next.js 14+** (React + TypeScript)
- **TailwindCSS** + **shadcn/ui** for styling
- **Framer Motion** for animations
- **React Flow** for graph editing
- **react-three-fiber** + **drei** for 3D visualizations
- **ECharts** for dashboards
- **TanStack Query** for data fetching

### Backend
- **GraphQL API** (Apollo Server + Fastify)
- **WebSockets** for real-time updates
- **PostgreSQL** for core data
- **Keycloak** for sovereign identity management (NO Azure)
- **Blockchain** integration for immutable records

## Getting Started

### Prerequisites
- Node.js 18+ 
- pnpm (recommended) or npm/yarn

### Installation

```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start
```

### Development

```bash
# Type checking
pnpm type-check

# Linting
pnpm lint

# Formatting
pnpm format

# Testing
pnpm test
pnpm test:coverage
```

### Environment Variables

Create a `.env.local` file in the root directory with the following variables:

```env
# GraphQL API
NEXT_PUBLIC_GRAPHQL_ENDPOINT=/api/graphql

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

# Sovereign Identity (Keycloak) - NO Azure dependencies
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=portal-client
KEYCLOAK_CLIENT_SECRET=your-client-secret

# Multi-Tenancy
ENABLE_MULTI_TENANT=true

# Monitoring (optional)
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=

# Analytics (optional)
NEXT_PUBLIC_ANALYTICS_ID=
```

See [ENV_EXAMPLES.md](./docs/ENV_EXAMPLES.md) for complete environment variable documentation.

## Project Structure

```
Sankofa/
├── docs/                    # Documentation
│   ├── brand/              # Brand documentation
│   └── architecture/        # Technical architecture
├── infrastructure/          # Infrastructure management
│   ├── proxmox/            # Proxmox VE management
│   ├── omada/              # TP-Link Omada management
│   ├── network/            # Network infrastructure
│   ├── monitoring/         # Monitoring and observability
│   └── inventory/          # Infrastructure inventory
├── crossplane-provider-proxmox/  # Crossplane provider for Proxmox
├── src/
│   ├── app/                # Next.js app router pages
│   ├── components/         # React components
│   │   ├── ui/            # UI components (shadcn/ui)
│   │   ├── 3d/            # 3D visualization components
│   │   ├── dashboards/    # Dashboard components
│   │   ├── editors/       # Graph/flow editors
│   │   └── well-architected/ # WAF components
│   ├── lib/               # Utilities and helpers
│   ├── styles/           # Global styles
│   └── content/          # Content files
├── public/               # Static assets
│   └── brand/           # Brand assets
└── package.json
```

## Ecosystem Architecture

**Sankofa Ltd** serves as the technical nexus for all system operations and integrations, functioning as the central hub for infrastructure, data exchange, and platform orchestration. ([Reference: https://sankofa.nexus](https://sankofa.nexus))

**Sankofa** serves as the overarching sovereign authority—governing identity, policy, compliance, and ecosystem structure.

**Sankofa Phoenix** is the sovereign digital cloud that powers the entire system—compute, identity, AI, transactions, and marketplace. All computing resources, hosting environments, and cloud-based services are powered by **Phoenix**, which acts as the dedicated cloud service provider.

As Microsoft uses Azure to deliver global cloud capabilities, Sankofa uses Phoenix to deliver sovereign, interoperable, and programmable digital infrastructure.

See [Ecosystem Architecture](./docs/ecosystem-architecture.md) for detailed information.

## Brand Philosophy

Sankofa Phoenix is built on the principle of **Remember → Retrieve → Restore → Rise**:

- **Remember**: Where we came from
- **Retrieve**: What was essential
- **Restore**: Identity and sovereignty
- **Rise**: Forward with purpose

## Documentation

### Quick Links
- **[Project Status](./PROJECT_STATUS.md)** - Current project status and recent changes
- **[Configuration Guide](./docs/CONFIGURATION_GUIDE.md)** - Setup and configuration instructions
- **[Environment Variables](./ENV_EXAMPLES.md)** - Environment variable examples
- **[Infrastructure Management](./infrastructure/README.md)** - Proxmox, Omada, and infrastructure management
- **[Tenant Management](./docs/tenants/TENANT_MANAGEMENT.md)** - Multi-tenant operations guide
- **[Billing Guide](./docs/tenants/BILLING_GUIDE.md)** - Advanced billing (superior to Azure)
- **[Identity Setup](./docs/tenants/IDENTITY_SETUP.md)** - Keycloak configuration

### Comprehensive Documentation

See the `/docs` directory for:
- **[Project Completion Plan](./docs/PROJECT_COMPLETION_PLAN.md)** - Comprehensive development plan with phases, tasks, and timelines
- **[Plan Summary](./docs/PLAN_SUMMARY.md)** - Quick reference guide to the project plan
- **[Deployment Guide](./docs/DEPLOYMENT.md)** - Production deployment instructions
- **[Development Guide](./docs/DEVELOPMENT.md)** - Development setup and workflow
- **[Testing Guide](./docs/TESTING.md)** - Testing strategies and examples
- Brand philosophy and positioning
- Product naming system
- Technical architecture
- Well-Architected Framework approach

### Historical Reports
- Archived completion and status reports: `docs/archive/`
- Status documents: `docs/status/`

## License

[To be determined]

---

**Sankofa Phoenix** — The sovereign cloud born of fire and ancestral wisdom.

**Sankofa** — Remember. Retrieve. Restore. Rise.