Fullstack Engineering Protocol

1. INTRODUCTION

This document defines the standard operating procedures for Fullstack Development at Moustachir Com. It applies to all Fullstack Developers working on TypeScript-based projects, whether using tRPC for type-safe APIs or traditional REST architectures.

For general engineering standards (Git Flow, Testing Strategy, Code Quality), refer to the General Engineering Protocol.

---

2. ONBOARDING CHECKLIST

Goal: First fullstack feature (UI + API) deployed to staging in 72 hours.

2.1 Access Provisioning

• GitHub: Accept invite to the Organization.
• Cloud Services: Access to deployment platforms (Vercel, Railway, AWS, etc.).
• Database: Credentials for development and staging databases.
• Notion: Access to the Development Board.
• Figma: Viewer access to design files.

2.2 Environment Setup

• Node.js: Use the LTS version specified in .nvmrc (typically via nvm or fnm).
• Package Manager: We strictly use pnpm (unless specified otherwise).
• Docker: Ensure Docker Desktop is running for local database containers.
• IDE: VS Code is recommended with the following extensions:
  • Biome
  • Tailwind CSS IntelliSense
  • Prisma (if using Prisma ORM)
  • Docker
  • Database client extension
  • GitLens
• Browser Tools: Install React DevTools.

2.3 Repository Setup

1. Clone the main repository: git clone <repo-url>
2. Install dependencies: pnpm install
3. Copy .env.example to .env and populate keys (ask Team Lead for secrets).
4. Start local services: docker-compose up -d (if applicable)
5. Run database migrations: pnpm db:migrate or pnpm prisma migrate dev
6. Seed the database: pnpm db:seed (if seed script exists)
7. Run the development server: pnpm dev
8. Verify the app runs at http://localhost:3000 (or specified port).

---

3. DAILY WORKFLOW

3.1 Feature Development Process

Always develop vertically (database → backend → frontend → testing):

• Database Schema: Define or update Prisma models.
• Backend Logic: Create API endpoints (tRPC procedures or REST routes).
• Frontend Integration: Build UI components and connect to API.
• Testing: Verify the entire flow works end-to-end.

3.2 Database Management

• Migrations: Never modify the database schema directly. Always use Prisma migrations.
• Schema First: Update schema.prisma, then migrate.
• Seed Data: Maintain a seed.ts script for local development data.
• Indexing: Add indexes for frequently queried fields.

3.3 API Development

Option A: tRPC Projects

• Use Zod for input validation (always).
• Organize routers by domain (users, posts, auth, etc.).
• Use publicProcedure for public endpoints, protectedProcedure for authenticated routes.
• Keep procedures focused. Complex logic should be in service files.

Option B: REST API Projects

• Follow RESTful conventions (GET, POST, PUT, DELETE).
• Validate input with Zod at the controller level.
• Return consistent error responses with proper HTTP status codes.
• Document endpoints with JSDoc or OpenAPI/Swagger.

3.4 Frontend Integration

• Use React Query (TanStack Query) for data fetching and caching.
• Handle loading, error, and success states explicitly.
• Keep API calls in custom hooks for reusability.
• Follow the project's established patterns for API integration.

3.5 Authentication & Authorization

• Authentication: Implement using NextAuth.js, Clerk, or Supabase Auth.
• Session Management: Use secure HTTP-only cookies (never store JWT in localStorage).
• Authorization: Implement role-based access control (RBAC) in middleware.
• Protected Routes: Guard both frontend routes and backend endpoints.

3.6 State Management

• Server State: Use React Query (TanStack Query) for all API data.
• Client State: Use Zustand or React Context for UI state (modals, forms, etc.).
• Avoid Redux unless the project explicitly requires it.

3.7 Styling

• Tailwind CSS: Primary styling method.
• Component Library: Use shadcn/ui for common components (buttons, inputs, dialogs).
• Responsive Design: Mobile-first approach. Test on multiple screen sizes.

3.8 Performance

• Code Splitting: Use dynamic imports for large components.
• Image Optimization: Use Next.js <Image> component.
• Lazy Loading: Implement for off-screen content.
• Database Optimization: Use indexes and avoid N+1 queries.
• Caching: Implement Redis for expensive queries where appropriate.

3.9 Security

• Input validation on all endpoints (Zod).
• SQL injection prevention (use Prisma, never raw queries).
• XSS prevention (sanitize user inputs).
• CSRF protection for state-changing operations.
• Authentication on protected routes (both frontend and backend).
• Rate limiting on public endpoints.
• Environment variables for secrets (never commit .env to Git).