# MentorStack Technical Specification
## Version Requirements
### Frontend Core
- React: 18.2.0
- TypeScript: 5.0.0+
- @inertiajs/react: 1.0.14
- @inertiajs/core: 1.0.14
- [Link]-client: 4.7.4
- vite: 5.0.10
### Backend Core
- Python: 3.11+
- Flask: 3.0.0
- flask-socketio: 5.3.6
- flask-inertia: 0.3.2
- gunicorn: 21.2.0
### Development Dependencies
- @testing-library/react: 14.1.2
- @testing-library/jest-dom: 6.1.5
- @vitejs/plugin-react: 4.2.1
- vitest: 1.1.0
- cypress: 13.6.1
- pytest: 7.4.3
- pytest-cov: 4.1.0
## Project Structure
```
mentorstack/
├── frontend/
│ ├── src/
│ │ ├── assets/ # Static assets
│ │ │ ├── images/ # Image assets
│ │ │ └── styles/ # Global styles
│ │ │
│ │ ├── components/ # Reusable components
│ │ │ ├── common/ # Shared components
│ │ │ │ ├── [Link]
│ │ │ │ ├── [Link]
│ │ │ │ └── [Link]
│ │ │ │
│ │ │ ├── forms/ # Form components
│ │ │ │ ├── [Link]
│ │ │ │ └── [Link]
│ │ │ │
│ │ │ └── realtime/ # WebSocket components
│ │ │ ├── [Link]
│ │ │ └── [Link]
│ │ │
│ │ ├── hooks/ # Custom React hooks
│ │ │ ├── [Link] # Authentication hook
│ │ │ ├── [Link] # WebSocket hook
│ │ │ └── [Link] # Form handling hook
│ │ │
│ │ ├── layouts/ # Layout components
│ │ │ ├── [Link] # Authenticated layout
│ │ │ └── [Link] # Public layout
│ │ │
│ │ ├── pages/ # [Link] pages
│ │ │ ├── Auth/
│ │ │ │ ├── [Link]
│ │ │ │ └── [Link]
│ │ │ │
│ │ │ ├── Dashboard/
│ │ │ │ ├── [Link]
│ │ │ │ └── [Link]
│ │ │ │
│ │ │ └── Waitlist/
│ │ │ └── [Link]
│ │ │
│ │ ├── services/ # API and service layer
│ │ │ ├── [Link] # API client
│ │ │ ├── [Link] # Auth service
│ │ │ └── [Link] # WebSocket service
│ │ │
│ │ ├── stores/ # State management
│ │ │ ├── [Link]
│ │ │ └── [Link]
│ │ │
│ │ ├── types/ # TypeScript definitions
│ │ │ ├── [Link] # API types
│ │ │ ├── [Link] # Data models
│ │ │ └── [Link] # WebSocket types
│ │ │
│ │ └── utils/ # Utility functions
│ │ ├── [Link] # Formatting utilities
│ │ └── [Link] # Validation helpers
│ │
│ ├── tests/
│ │ ├── components/ # Component tests
│ │ │ ├── common/
│ │ │ └── forms/
│ │ │
│ │ ├── e2e/ # Cypress tests
│ │ │ ├── [Link]
│ │ │ └── [Link]
│ │ │
│ │ ├── hooks/ # Hook tests
│ │ └── utils/ # Utility tests
│ │
│ ├── cypress/
│ │ ├── fixtures/ # Test data
│ │ └── support/ # Test helpers
│ │
│ ├── public/ # Static files
│ │ └── [Link]
│ │
│ ├── [Link] # Entry HTML
│ ├── [Link] # Vite configuration
│ ├── [Link] # TypeScript configuration
│ ├── [Link] # Cypress configuration
│ └── [Link] # Vitest configuration
│
└── backend/ # Flask backend (separate spec)
## Component Guidelines
### Common Components
Each common component should:
- Be fully typed with TypeScript
- Include PropTypes
- Have associated test file
- Include Storybook story
- Be responsive by default
Example Button Component:
```typescript
// components/common/[Link]
import React from 'react';
interface ButtonProps {
variant: 'primary' | 'secondary' | 'danger';
size: 'sm' | 'md' | 'lg';
children: [Link];
onClick?: () => void;
disabled?: boolean;
}
export const Button: [Link]<ButtonProps> = ({
variant,
size,
children,
onClick,
disabled
}) => {
// Implementation
};
```
### Page Components
Each page component should:
- Use [Link] Page type
- Include proper TypeScript interfaces for props
- Handle loading and error states
- Implement proper SEO meta tags
Example Page Component:
```typescript
// pages/Dashboard/[Link]
import { Page } from '@inertiajs/inertia';
import { AppLayout } from '@/layouts/AppLayout';
interface DashboardProps {
stats: {
totalMentors: number;
activeChats: number;
};
}
const Dashboard: Page<DashboardProps> = ({ stats }) => {
return (
<AppLayout title="Dashboard">
{/* Implementation */}
</AppLayout>
);
};
```
## Testing Structure
### Unit Tests (Vitest)
- Test file location: Next to the component/hook
- Naming convention: `*.[Link]` or `*.[Link]`
- Coverage requirements: 80% minimum
Example Test:
```typescript
// components/common/[Link]
import { render, fireEvent } from '@testing-library/react';
import { Button } from './Button';
describe('Button', () => {
it('renders correctly', () => {
const { getByText } = render(
<Button variant="primary" size="md">
Click me
</Button>
);
expect(getByText('Click me')).toBeInTheDocument();
});
});
```
### E2E Tests (Cypress)
- Test file location: `cypress/e2e/`
- Naming convention: `*.[Link]`
- Required test cases:
- Authentication flow
- Waitlist signup
- Navigation
- Form submissions
Example Cypress Test:
```typescript
// cypress/e2e/[Link]
describe('Authentication', () => {
it('should login successfully', () => {
[Link]('/login');
[Link]('[data-test="email"]').type('user@[Link]');
[Link]('[data-test="password"]').type('password');
[Link]('[data-test="login-button"]').click();
[Link]().should('include', '/dashboard');
});
});
```
## Development Setup
### Required Tools
- [Link] 20.x
- pnpm 8.x
- Python 3.11+
- Docker & Docker Compose
### Environment Setup
```bash
# Frontend setup
cd frontend
pnpm install
pnpm dev
# Run tests
pnpm test # Unit tests
pnpm test:e2e # E2E tests
pnpm test:cover # Coverage report
```
### Environment Variables
```env
# .env
VITE_API_URL=[Link]
VITE_WS_URL=[Link]
VITE_APP_ENV=development
```
## Build & Deployment
### Production Build
```bash
# Frontend build
pnpm build
# Output directory: dist/
```
### Docker Build
```dockerfile
# Frontend Dockerfile
FROM node:20-alpine as builder
WORKDIR /app
COPY [Link] [Link] ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY [Link] /etc/nginx/conf.d/[Link]
```
## Performance Requirements
### Core Web Vitals Targets
- Largest Contentful Paint (LCP): < 2.5s
- First Input Delay (FID): < 100ms
- Cumulative Layout Shift (CLS): < 0.1
### Bundle Size Limits
- Main bundle: < 200KB (gzipped)
- Chunk size: < 50KB (gzipped)
- Image optimization required
## Security Requirements
### Frontend Security Measures
- CSRF protection via [Link]
- XSS prevention
- Content Security Policy
- Secure cookie handling
- Input sanitization
### Authentication
- Token-based auth with HTTP-only cookies
- Session timeout handling
- Rate limiting on auth endpoints
- Password strength requirements
## Monitoring & Analytics
### Error Tracking
- Sentry integration
- Error boundary implementation
- Console error tracking
### Performance Monitoring
- Web Vitals tracking
- Custom performance marks
- Network request timing
### User Analytics
- Google Analytics 4
- Custom event tracking
- User journey mapping