6f28146ac3
- Complete project structure with Next.js frontend - GraphQL API backend with Apollo Server - Portal application with NextAuth - Crossplane Proxmox provider - GitOps configurations - CI/CD pipelines - Testing infrastructure (Vitest, Jest, Go tests) - Error handling and monitoring - Security hardening - UI component library - Documentation
2.7 KiB
2.7 KiB
Development Guide
This guide will help you set up your development environment for Phoenix Sankofa Cloud.
Prerequisites
- Node.js 18+ and pnpm (or npm/yarn)
- PostgreSQL 14+ (for API)
- Go 1.21+ (for Crossplane provider)
- Docker (optional, for local services)
Initial Setup
1. Clone the Repository
git clone https://github.com/yourorg/Sankofa.git
cd Sankofa
2. Install Dependencies
# Main application
pnpm install
# Portal
cd portal
npm install
cd ..
# API
cd api
npm install
cd ..
# Crossplane Provider
cd crossplane-provider-proxmox
go mod download
cd ..
3. Set Up Environment Variables
Create .env.local files:
# Root .env.local
cp .env.example .env.local
# Portal .env.local
cd portal
cp .env.example .env.local
cd ..
# API .env.local
cd api
cp .env.example .env.local
cd ..
4. Set Up Database
# Create database
createdb sankofa
# Run migrations
cd api
npm run db:migrate
Running the Application
Development Mode
# Main app (port 3000)
pnpm dev
# Portal (port 3001)
cd portal
npm run dev
# API (port 4000)
cd api
npm run dev
Running Tests
# Main app tests
pnpm test
# Portal tests
cd portal
npm test
# Crossplane provider tests
cd crossplane-provider-proxmox
go test ./...
Project Structure
Sankofa/
├── src/ # Main Next.js app
├── portal/ # Portal application
├── api/ # GraphQL API server
├── crossplane-provider-proxmox/ # Crossplane provider
├── gitops/ # GitOps configurations
├── cloudflare/ # Cloudflare configs
└── docs/ # Documentation
Common Tasks
Adding a New Component
- Create component in
src/components/ - Add tests in
src/components/**/*.test.tsx - Export from appropriate index file
- Update Storybook (if applicable)
Adding a New API Endpoint
- Add GraphQL type definition in
api/src/schema/typeDefs.ts - Add resolver in
api/src/schema/resolvers.ts - Add service logic in
api/src/services/ - Add tests
Database Migrations
cd api
# Create migration
npm run db:migrate:create migration-name
# Run migrations
npm run db:migrate
Debugging
Frontend
- Use React DevTools
- Check browser console
- Use Next.js debug mode:
NODE_OPTIONS='--inspect' pnpm dev
Backend
- Use VS Code debugger
- Check API logs
- Use GraphQL Playground at
http://localhost:4000/graphql
Code Quality
Linting
pnpm lint
Type Checking
pnpm type-check
Formatting
pnpm format
Troubleshooting
See TROUBLESHOOTING.md for common issues and solutions.