Chirp - Social Media Platform

A Twitter-like social media platform built as a monorepo with TanStack Start, React 19, gRPC, StyleX, and SQLite.

NOTE: Task details are documented in TASK.md

Chirp is a full-stack monorepo application with:

• User App (apps/client-user) - Consumer-facing social media application
• Admin App (apps/client-admin) - Administrative dashboard for content moderation
• API Server (apps/api) - gRPC-based backend service

# Install dependencies
pnpm install

# Generate protocol buffers
pnpm run proto:generate

# Setup database
pnpm run db:generate
pnpm run db:migrate
pnpm run db:seed

# Start all services (API + User App + Admin App)
pnpm run dev

After running the seed script:

• alice@test.com / password123
• bob@test.com / password123
• charlie@test.com / password123
• diana@test.com / password123
• eve@test.com / password123

• admin@chirp.com / admin123

• Authentication - Email/password registration, login, session management
• Posts (Chirps) - Create, edit (within 5 min), delete text posts (max 280 chars)
• Comments - Add/delete comments, nested threads (1 level deep)
• Likes - Like/unlike posts and comments
• User Profiles - View profiles, edit own profile (name, bio, avatar)
• Follow System - Follow/unfollow users, follower/following counts

• Home Feed - Posts from followed users
• Explore Feed - All recent posts
• Search - Find posts by content, users by name/username

• Bookmarks - Save posts for later, dedicated bookmarks page
• Notifications - Alerts for likes, comments, follows, and mentions
• Mentions - @username linking in posts and comments

• Dashboard - Platform statistics and overview
• User Management - View, search, suspend/unsuspend users
• Post Management - Moderate and delete posts
• Comment Management - Moderate and delete comments
• Reports - Handle user reports on content
• Audit Logs - Track all administrative actions

chirp/
├── apps/
│   ├── api/                    # gRPC API server
│   │   ├── src/
│   │   │   ├── grpc/           # gRPC handlers and server
│   │   │   ├── services/       # Business logic services
│   │   │   └── db/             # Database connection and seed
│   │   └── package.json
│   │
│   ├── client-user/            # User-facing TanStack Start app
│   │   ├── src/
│   │   │   ├── components/     # React components
│   │   │   ├── routes/         # File-based routing
│   │   │   ├── server/         # Server functions
│   │   │   └── tokens.stylex.ts # Design tokens
│   │   ├── tests/
│   │   │   ├── unit/           # Vitest unit tests
│   │   │   └── e2e/            # Playwright E2E tests
│   │   └── package.json
│   │
│   └── client-admin/           # Admin TanStack Start app
│       ├── src/
│       │   ├── components/     # Admin UI components
│       │   ├── routes/         # Admin routes
│       │   └── server/         # Admin server functions
│       ├── tests/
│       │   ├── unit/           # Vitest unit tests
│       │   └── e2e/            # Playwright E2E tests
│       └── package.json
│
├── packages/
│   ├── db-schema/              # Drizzle ORM schema definitions
│   ├── proto/                  # Protocol buffer definitions
│   ├── grpc-client/            # gRPC client library
│   ├── ui/                     # Shared UI components (StyleX)
│   └── shared-types/           # Shared TypeScript types
│
├── db/
│   └── migrations/             # Database migrations
│
├── tooling/
│   └── typescript/             # Shared TypeScript config
│
└── package.json                # Root monorepo config

pnpm run dev              # Start all services
pnpm run dev:user         # Start only user app
pnpm run dev:admin        # Start only admin app
pnpm run dev:api          # Start only API server

pnpm run build            # Build all packages
pnpm run typecheck        # Type check all packages
pnpm run lint             # Lint all packages
pnpm run lint:fix         # Fix linting issues

pnpm run test             # Run all tests
pnpm run test:unit        # Run unit tests
pnpm run test:e2e         # Run E2E tests

pnpm run db:generate      # Generate database migrations
pnpm run db:migrate       # Run database migrations
pnpm run db:seed          # Seed database with test data

pnpm run proto:generate   # Generate TypeScript from proto files
pnpm run clean            # Clean all build artifacts

Each app (apps/client-user, apps/client-admin, apps/api) has:

pnpm run dev              # Start development server
pnpm run build            # Build for production
pnpm run typecheck        # Type check
pnpm run test             # Run tests
pnpm run test:unit        # Run unit tests only
pnpm run test:e2e         # Run E2E tests only (client apps)

• users - User accounts and profiles
• posts - User posts/chirps
• comments - Post comments
• likes - Post and comment likes
• follows - User follow relationships

• bookmarks - Saved posts
• notifications - User notifications
• reports - Content reports
• audit_logs - Admin action logs

1. Database: Add schema in packages/db-schema/src/schema.ts
2. Proto: Define gRPC service in packages/proto/protos/
3. API: Implement service in apps/api/src/services/
4. Handler: Add gRPC handler in apps/api/src/grpc/handlers/
5. Client: Update packages/grpc-client/src/client.ts
6. Server Functions: Add in apps/client-*/src/server/functions/
7. Components: Create UI in apps/client-*/src/components/
8. Routes: Add pages in apps/client-*/src/routes/
9. Tests: Add unit tests and E2E tests

# Run all tests
pnpm run test

# Run specific app tests
cd apps/client-user && pnpm run test:e2e

# Run with UI mode
cd apps/client-user && pnpm exec playwright test --ui

# Clean everything and start fresh
pnpm run clean
rm -f chirp.db chirp.db-shm chirp.db-wal
pnpm install
pnpm run proto:generate
pnpm run db:generate
pnpm run db:migrate
pnpm run db:seed

The API uses gRPC with the following services:

• AuthService - Authentication (login, register, validate session)
• UsersService - User management and profiles
• PostsService - Post CRUD operations
• CommentsService - Comment operations
• LikesService - Like/unlike functionality
• FollowsService - Follow/unfollow users
• BookmarksService - Bookmark management
• NotificationsService - Notification handling
• SearchService - Search posts and users
• AdminService - Admin-only operations

Proto definitions are in packages/proto/protos/.

This repo was completed as the LLM Web Refactoring Assessment for a senior engineering role at Speechify. I'm publishing it as a reference for future candidates.

You receive a full-stack monorepo (this "Chirp" app) with 5 issues to fix in 90 minutes. AI/LLM tool usage is explicitly permitted and encouraged. The issues test security awareness, performance optimization, error handling, testing, and CI/CD — standard senior engineer skills.

1. Credential Problem — SHA-256 with hardcoded salt, hardcoded JWT secrets, predictable IDs
2. Query Performance — N+1 query anti-pattern across multiple services
3. Error Handling & Observability — inconsistent error handling, no request tracing
4. Test Infrastructure — coverage gaps, isolation issues
5. Build Pipeline — no CI, no pre-commit hooks

All 5 issues completed with additional improvements beyond scope. Full audit documented in AUDIT.md.

• Read the entire codebase first. The task description says this explicitly and they mean it. Understanding the architecture is more valuable than rushing to fix things.
• AI tools are your friend, but understanding matters. The assessment evaluates whether your fixes demonstrate genuine understanding of the system, not just pattern-matching.
• AUDIT.md is your chance to shine. The code changes alone don't tell the full story. Document your reasoning — what you found, why it's a problem, what you considered, what you chose and why.
• Prioritize by severity. The credential problem is CRITICAL. Fix that first. If you run out of time on Issue 4-5, your AUDIT.md can still show you understood them.
• Don't refactor the neighborhood. The task says "minimal, surgical changes." They mean it. Fix the problem, prove it with tests, move on.
• The "unfixed issues" section shows maturity. Listing what you would fix with more time demonstrates senior-level judgment about scope and prioritization.

90 minutes is tight for 5 issues. My approach:

• ~15 min reading the full codebase
• ~20 min on Issue 1 (credentials — highest severity)
• ~15 min on Issue 2 (N+1 queries — most impactful)
• ~15 min on Issue 3 (error handling — most files touched)
• ~10 min on Issue 4 (tests)
• ~10 min on Issue 5 (CI/CD)
• ~5 min writing AUDIT.md

Feel free to study this repo, learn from the patterns, or use it as a benchmark. Good luck.

MIT License — Built by David Hsu