SecPal Frontend

React/TypeScript frontend for the SecPal platform.

📋 Prerequisites

• Node.js >= 20.0.0
• npm >= 10.0.0
• Git with GPG signing configured

🚀 Getting Started

Clone Repository

cd ~/code/SecPal
git clone https://github.com/SecPal/frontend.git
cd frontend

Install Dependencies

npm install

Setup Pre-Commit Hooks

./scripts/setup-pre-commit.sh

🛠️ Development

Start Development Server

npm run dev

Build for Production

npm run build

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:ui

# Generate coverage report
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Type checking
npm run typecheck

# Format code
npm run format

# Check formatting
npm run format:check

Pre-Push Validation

Before every push, run the preflight script:

./scripts/preflight.sh

This runs:

• ✅ Prettier formatting check
• ✅ Markdownlint
• ✅ REUSE compliance
• ✅ ESLint
• ✅ TypeScript type checking
• ✅ Vitest test suite
• ✅ PR size validation (≤600 lines)

📁 Project Structure

frontend/
├── src/
│   ├── components/     # React components
│   ├── hooks/          # Custom hooks
│   ├── pages/          # Page components
│   ├── services/       # API services
│   ├── types/          # TypeScript types
│   ├── utils/          # Utility functions
│   ├── App.tsx         # Root component
│   └── main.tsx        # Entry point
├── public/             # Static assets
├── tests/              # Test files
├── .github/            # GitHub workflows and templates
├── scripts/            # Build and utility scripts
└── package.json        # Dependencies and scripts

🧪 Testing Guidelines

• Coverage target: 80%+ for new code, 100% for critical paths
• TDD mandatory: Write failing test first, implement, refactor
• Use @testing-library/react for component testing
• Mock API calls with MSW (Mock Service Worker)
• Test user-visible behavior, not implementation

🔒 Security

• Secret scanning: Enabled with push protection
• Dependabot: Daily security updates (04:00 CET)
• SAST: CodeQL analysis on pull requests
• Never commit: API keys, passwords, tokens, .env files

See SECURITY.md for reporting vulnerabilities.

📝 Contributing

See CONTRIBUTING.md for guidelines.

Branch Naming Convention

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation
• refactor/ - Code refactoring
• test/ - Test additions/fixes
• chore/ - Maintenance
• spike/ - Exploration (no TDD required, cannot merge to main)

Commit Messages

Follow Conventional Commits:

feat: add user authentication
fix: resolve memory leak in dashboard
docs: update API integration guide
test: add tests for login form

📜 License

AGPL-3.0-or-later - See LICENSE for details.

This project is REUSE 3.3 compliant. All files contain SPDX license headers.

🔗 Related Repositories

• Contracts - OpenAPI 3.1 specifications
• .github - Organization-wide settings and documentation
• API - Laravel backend (planned)

📞 Support

• Issues: GitHub Issues
• Security: See SECURITY.md
• Code of Conduct: CODE_OF_CONDUCT.md

---

Maintained by: SecPal Team Last Updated: October 2025