jeffjhunter_ai-persona-os/examples/coding-assistant/KNOWLEDGE.md

KNOWLEDGE.md — Technical Expertise

---

Tech Stack

Primary Languages

Language	Use Case	Version
TypeScript	Frontend, Backend	5.x
Python	Scripts, ML	3.11+
SQL	Database queries	PostgreSQL

Frameworks

Framework	Purpose	Docs
React	Frontend UI	reactjs.org
Next.js	Full-stack	nextjs.org
FastAPI	Python API	fastapi.tiangolo.com

Infrastructure

Service	Purpose
Vercel	Frontend hosting
Railway	Backend hosting
PostgreSQL	Primary database
Redis	Caching, queues

---

Codebase Patterns

File Structure

src/
├── components/    → React components
├── pages/         → Next.js pages
├── api/           → API routes
├── lib/           → Shared utilities
├── hooks/         → Custom React hooks
└── types/         → TypeScript types

Naming Conventions

• Components: PascalCase.tsx
• Utilities: camelCase.ts
• Types: PascalCase with I prefix for interfaces
• Constants: SCREAMING_SNAKE_CASE

Code Style

• Prettier for formatting
• ESLint for linting
• Prefer const over let
• Use async/await over .then()
• Destructure props and imports

---

Common Patterns

API Calls

// Example pattern — not a live endpoint
const fetchData = async () => {
  try {
    const res = await fetch('/api/endpoint');
    if (!res.ok) throw new Error('Failed to fetch');
    return await res.json();
  } catch (error) {
    console.error('Fetch error:', error);
    throw error;
  }
};

Error Handling

// Use try/catch with specific error types
try {
  await riskyOperation();
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation errors
  } else if (error instanceof NetworkError) {
    // Handle network errors
  } else {
    // Unknown error, rethrow
    throw error;
  }
}

Testing Pattern

describe('Component', () => {
  it('should render correctly', () => {
    // Arrange
    const props = { ... };
    
    // Act
    render(<Component {...props} />);
    
    // Assert
    expect(screen.getByText('...')).toBeInTheDocument();
  });
});

---

Environment Variables

Variable	Purpose	Location
DATABASE_URL	DB connection	.env.local
YOUR_API_KEY	External API	.env.local
NODE_ENV	Environment	Auto-set

Never commit .env.local to git.

---

Deployment

Staging

• Branch: develop
• URL: staging.example.com
• Auto-deploys on push

Production

• Branch: main
• URL: example.com
• Requires PR merge

Rollback

# Revert to previous deployment
vercel rollback

---

Common Issues

"Module not found"

• Run npm install
• Check import path
• Verify file exists

"Type error"

• Check TypeScript types
• Ensure proper null checks
• Update type definitions

"CORS error"

• Check API route config
• Verify allowed origins
• Check request headers

---

Useful Commands

# Development
npm run dev          # Start dev server
npm run build        # Build for production
npm run test         # Run tests
npm run lint         # Run linter

# Git
git stash            # Save changes temporarily
git stash pop        # Restore stashed changes
git rebase -i HEAD~3 # Interactive rebase

# Database
npm run db:migrate   # Run migrations
npm run db:seed      # Seed database
npm run db:reset     # Reset database

---

Part of AI Persona OS by Jeff J Hunter — https://os.aipersonamethod.com