// Use clsx for conditional classes
import clsx from 'clsx';
```
### Form Handling with Formik
```typescript
import { Formik, Form, Field } from 'formik';
import * as Yup from 'yup';
const validationSchema = Yup.object({
name: Yup.string().required('Name is required'),
email: Yup.string().email('Invalid email').required('Email is required')
});
export default function ClientForm() {
return (
{
try {
await saveClient(values);
} finally {
setSubmitting(false);
}
}}
>
{({ errors, touched, isSubmitting }) => (
)}
);
}
```
---
## Backend Standards
### Express Route Structure
```javascript
// Standard route pattern
const express = require('express');
const router = express.Router();
const { authMiddleware } = require('../middleware/auth');
const { validate } = require('../middleware/validation');
const clientController = require('../controllers/clientController');
// GET list (with pagination)
router.get(
'/api/clients',
authMiddleware,
clientController.list
);
// POST create
router.post(
'/api/clients',
authMiddleware,
validate(clientSchema),
clientController.create
);
// GET by ID
router.get(
'/api/clients/:id',
authMiddleware,
clientController.getById
);
// PUT update
router.put(
'/api/clients/:id',
authMiddleware,
validate(clientUpdateSchema),
clientController.update
);
// DELETE
router.delete(
'/api/clients/:id',
authMiddleware,
clientController.delete
);
module.exports = router;
```
### Controller Pattern
```javascript
// controllers/clientController.js
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();
const clientController = {
async list(req, res, next) {
try {
const { organizationId } = req.user;
const { page = 1, limit = 20, status } = req.query;
const where = { organizationId };
if (status) where.status = status;
const clients = await prisma.client.findMany({
where,
skip: (page - 1) * limit,
take: parseInt(limit),
orderBy: { createdAt: 'desc' }
});
const total = await prisma.client.count({ where });
res.json({
success: true,
data: clients,
pagination: {
page: parseInt(page),
limit: parseInt(limit),
total,
pages: Math.ceil(total / limit)
}
});
} catch (error) {
next(error);
}
},
async create(req, res, next) {
try {
const { organizationId } = req.user;
const data = {
...req.body,
organizationId,
createdById: req.user.id
};
const client = await prisma.client.create({ data });
res.status(201).json({
success: true,
data: client
});
} catch (error) {
next(error);
}
},
async getById(req, res, next) {
try {
const { organizationId } = req.user;
const { id } = req.params;
const client = await prisma.client.findFirst({
where: {
id,
organizationId // Critical: prevent cross-org access
}
});
if (!client) {
return res.status(404).json({
success: false,
error: 'Client not found'
});
}
res.json({
success: true,
data: client
});
} catch (error) {
next(error);
}
}
};
module.exports = clientController;
```
### API Response Format
```javascript
// Success response
{
success: true,
data: { /* resource or array */ }
}
// Success with pagination
{
success: true,
data: [/* resources */],
pagination: {
page: 1,
limit: 20,
total: 150,
pages: 8
}
}
// Error response
{
success: false,
error: "Descriptive error message"
}
// Validation error response
{
success: false,
error: "Validation failed",
details: [
{ field: "email", message: "Invalid email format" },
{ field: "name", message: "Name is required" }
]
}
```
### Input Validation (Joi)
```javascript
const Joi = require('joi');
const clientSchema = Joi.object({
name: Joi.string().required().min(2).max(100),
email: Joi.string().email().required(),
phone: Joi.string().optional().pattern(/^\d{10}$/),
riskLevel: Joi.string().valid('LOW', 'MEDIUM', 'HIGH', 'CRITICAL').required(),
metadata: Joi.object().optional()
});
// In routes
const { validate } = require('../middleware/validation');
router.post('/api/clients', authMiddleware, validate(clientSchema), controller.create);
```
### Error Handling
```javascript
// Custom error class
class ApiError extends Error {
constructor(message, statusCode = 500) {
super(message);
this.statusCode = statusCode;
this.name = 'ApiError';
}
}
// Error handler middleware (last middleware)
app.use((err, req, res, next) => {
console.error('[ERROR]', err);
if (err instanceof ApiError) {
return res.status(err.statusCode).json({
success: false,
error: err.message
});
}
// Prisma errors
if (err.code === 'P2002') {
return res.status(409).json({
success: false,
error: 'Resource already exists'
});
}
// Default error
res.status(500).json({
success: false,
error: process.env.NODE_ENV === 'production'
? 'Internal server error'
: err.message
});
});
```
---
## Database Patterns
### Prisma Query Patterns
```javascript
// Always include organizationId
const client = await prisma.client.findFirst({
where: {
id: clientId,
organizationId: req.user.organizationId
}
});
// Include related data
const client = await prisma.client.findFirst({
where: { id: clientId, organizationId },
include: {
alerts: {
where: { status: 'PENDING' },
orderBy: { createdAt: 'desc' }
},
decisions: true
}
});
// Select specific fields only
const clients = await prisma.client.findMany({
where: { organizationId },
select: {
id: true,
name: true,
riskLevel: true
}
});
// Pagination
const clients = await prisma.client.findMany({
where: { organizationId },
skip: (page - 1) * limit,
take: limit,
orderBy: { createdAt: 'desc' }
});
```
### Audit Trail Pattern
```javascript
// Create with audit trail
const decision = await prisma.professionalDecision.create({
data: {
...decisionData,
organizationId,
createdById: req.user.id,
createdAt: new Date()
}
});
// Update with audit trail
const updated = await prisma.professionalDecision.update({
where: { id: decisionId },
data: {
...updates,
updatedById: req.user.id,
updatedAt: new Date()
}
});
```
### Transaction Pattern
```javascript
const result = await prisma.$transaction(async (tx) => {
// Create client
const client = await tx.client.create({
data: { ...clientData, organizationId }
});
// Create initial alert
const alert = await tx.alert.create({
data: {
type: 'ONBOARDING',
clientId: client.id,
organizationId
}
});
// Log audit trail
await tx.auditLog.create({
data: {
action: 'CLIENT_CREATED',
resourceId: client.id,
userId: req.user.id,
organizationId
}
});
return { client, alert };
});
```
---
## Security Requirements
### Authentication
```javascript
// JWT middleware - verify and attach user
const authMiddleware = async (req, res, next) => {
try {
const token = req.headers.authorization?.replace('Bearer ', '');
if (!token) {
return res.status(401).json({
success: false,
error: 'Authentication required'
});
}
const decoded = jwt.verify(token, process.env.JWT_SECRET);
req.user = decoded; // Contains id, organizationId, role
next();
} catch (error) {
res.status(401).json({
success: false,
error: 'Invalid token'
});
}
};
```
### Password Handling
```javascript
const bcrypt = require('bcryptjs');
// Hash password before storing
const hashedPassword = await bcrypt.hash(password, 10);
// Never store plain text
await prisma.user.create({
data: {
email,
password: hashedPassword, // ALWAYS hashed
organizationId
}
});
// Verify password
const isValid = await bcrypt.compare(inputPassword, user.password);
```
### Input Sanitization
```javascript
// Sanitize user input to prevent XSS
const sanitizeHtml = require('sanitize-html');
const cleanContent = sanitizeHtml(userInput, {
allowedTags: ['b', 'i', 'em', 'strong'],
allowedAttributes: {}
});
```
### Environment Variables
```javascript
// NEVER commit secrets to git
// Use .env files (in .gitignore)
// .env
DATABASE_URL=postgresql://...
JWT_SECRET=your_secret_here_min_32_chars
JWT_REFRESH_SECRET=different_secret
// Access via process.env
const secret = process.env.JWT_SECRET;
// Validate required variables on startup
if (!process.env.JWT_SECRET) {
throw new Error('JWT_SECRET is required');
}
```
---
## Testing Standards
### Unit Test Structure (Jest)
```javascript
// __tests__/nexusDetector.test.js
const { SalesNexusDetector } = require('../services/SalesNexusDetector');
describe('SalesNexusDetector', () => {
let detector;
beforeEach(() => {
detector = new SalesNexusDetector();
});
describe('California Economic Nexus', () => {
it('should trigger RED alert when revenue exceeds $500k', () => {
const result = detector.detect({ CA: 650000 });
expect(result).toHaveLength(1);
expect(result[0]).toMatchObject({
severity: 'RED',
stateCode: 'CA',
threshold: 500000
});
});
});
});
```
### Integration Test (Supertest)
```javascript
const request = require('supertest');
const app = require('../app');
describe('POST /api/clients', () => {
it('should create client with valid data', async () => {
const response = await request(app)
.post('/api/clients')
.set('Authorization', `Bearer ${validToken}`)
.send({
name: 'Test Client',
email: 'test@example.com'
})
.expect(201);
expect(response.body.success).toBe(true);
expect(response.body.data.name).toBe('Test Client');
});
it('should enforce multi-tenant isolation', async () => {
// Create client in org 1
await createClient({ organizationId: 'org1' });
// Try to access with org 2 token
const response = await request(app)
.get('/api/clients')
.set('Authorization', `Bearer ${org2Token}`)
.expect(200);
// Should not see org 1's client
expect(response.body.data).toHaveLength(0);
});
});
```
---
## Code Review Checklist
### Security ✓
- [ ] Multi-tenant isolation enforced (organizationId filter)
- [ ] No hardcoded secrets or API keys
- [ ] Passwords hashed with bcrypt
- [ ] Input validation on all endpoints
- [ ] SQL injection prevented (Prisma parameterization)
- [ ] XSS prevented (React auto-escaping, input sanitization)
### Code Quality ✓
- [ ] TypeScript types defined (no `any`)
- [ ] Error handling implemented
- [ ] Consistent naming conventions
- [ ] No console.log in production code
- [ ] Comments explain "why", not "what"
### Testing ✓
- [ ] Tests added for new features
- [ ] Critical paths covered (nexus detection, auth)
- [ ] Multi-tenant isolation tested
### VaultCPA Specifics ✓
- [ ] Audit trail created for important operations
- [ ] Tax calculations verified against thresholds
- [ ] Professional decisions documented properly
- [ ] Database migrations are reversible
### Performance ✓
- [ ] No N+1 query patterns
- [ ] Pagination implemented for lists
- [ ] Appropriate indexes exist
- [ ] Large files handled efficiently
---
## File Naming Conventions
```
Frontend:
- Components: PascalCase (ClientCard.tsx)
- Pages: lowercase (page.tsx, layout.tsx)
- Utilities: camelCase (formatCurrency.ts)
- Types: PascalCase (types.ts with PascalCase interfaces)
Backend:
- Routes: camelCase (clientRoutes.js)
- Controllers: camelCase (clientController.js)
- Services: PascalCase (SalesNexusDetector.js)
- Tests: *.test.js or *.spec.js
```
---
## Common Anti-Patterns to Avoid
1. ❌ Missing organizationId filter → Data leakage
2. ❌ Using `any` type → Loss of type safety
3. ❌ Inline business logic in routes → Hard to test
4. ❌ Unhandled promise rejections → Server crashes
5. ❌ Missing error boundaries → Poor UX
6. ❌ N+1 queries → Performance issues
7. ❌ Hardcoded configuration → Deployment problems
8. ❌ Skipping validation → Security vulnerabilities
---
**When using this Skill:**
1. Reference specific sections when reviewing code
2. Cite examples when providing feedback
3. Link to this Skill in PR comments for context
4. Update this Skill when new patterns emerge