Developer Guide

Welcome to the Portfolio OS Developer Guide. This comprehensive resource covers everything you need to know to contribute effectively to the project.

Overview

Portfolio OS is a modern, production-grade monorepo built with Next.js, TypeScript, and Turborepo. It powers a complete portfolio ecosystem including a public site, admin dashboard, and shared component libraries.

Quick Navigation

Technology Stack at a Glance

Core Principles

Portfolio OS follows these development principles:

1. Type Safety First

• Strict TypeScript configuration across all packages
• No any types without explicit justification
• Comprehensive type coverage for API responses

2. Component Reusability

• Shared UI components in packages/ui
• Business logic in packages/lib
• Utilities in packages/utils

3. Performance Optimization

• Server Components by default
• Strategic client-side rendering
• Redis caching for expensive operations
• Image optimization with Next.js Image

4. Developer Experience

• Fast development with Turbo
• Hot Module Replacement (HMR)
• Comprehensive error messages
• Automated code quality checks

5. Automation

• PowerShell scripts for common tasks
• GitHub Actions for CI/CD
• Automated PR management
• Multi-agent development support

Project Structure Highlights

portfolio-os/
├── apps/
│   ├── site/           # Public portfolio (localhost:3000)
│   ├── dashboard/      # Admin dashboard (localhost:3001)
│   └── docs/           # Documentation site (localhost:3002)
│
├── packages/
│   ├── ui/             # Shared React components
│   ├── lib/            # Business logic & services
│   ├── utils/          # Utility functions
│   ├── db/             # Prisma schema & client
│   ├── hashnode/       # Hashnode API integration
│   ├── emails/         # Email templates
│   └── tsconfig/       # Shared TypeScript configs
│
├── scripts/            # PowerShell automation
│   ├── agent-management/
│   ├── pr-management/
│   ├── issue-management/
│   └── core-utilities/
│
└── docs/              # Technical documentation
    ├── setup/
    ├── automation/
    ├── api/
    └── troubleshooting/

Development Commands Reference

Working with the Monorepo

Understanding Turborepo

Turborepo orchestrates builds and tests across the monorepo:

• Caching: Build outputs are cached for speed
• Parallelization: Tasks run in parallel when possible
• Dependencies: Automatically builds dependencies first

PNPM Workspaces

Packages are linked using PNPM workspaces:

{
  "dependencies": {
    "@mindware-blog/ui": "workspace:*",
    "@mindware-blog/lib": "workspace:*"
  }
}

The workspace:* protocol links to the local package.

Best Practices

Getting Help

• Architecture Questions: See Architecture Overview
• Code Issues: Check Troubleshooting
• Setup Problems: Review Installation Guide
• Multi-Agent Dev: Explore Multi-Agent System

Next Steps

1. New to the project? Start with Architecture Overview
2. Ready to contribute? Review Development Workflow
3. Building features? Check Coding Standards
4. Working with packages? See Package System