Technical Brief - Annotation Platform Frontend Development
Project Overview
We’re building a web-based annotation platform that allows users to manage projects, upload media, and handle annotations. This is an MVP phase focusing on core functionality and solid UI/UX.
The mobile app that is focussed on the ‘data contribution’ users, who will annotate data from the web app to earn tokens.
Technical Stack
- Framework: Next.js 15 with App Router
- UI Components: shadcn/ui library
- Language: TypeScript
- Authentication: Supabase Auth
- Storage: Supabase Storage for media files
- State Management: React Server Components + Client Hooks where needed
Stakeholders and Users
Primary Stakeholders
Data Owners (Web App Users)
- Primary users of the web application
- Looking to get their data annotated efficiently
- Need to:
- Create and manage annotation projects
- Upload data (images, etc.)
- Monitor annotation progress
- Export annotated data
- Manage project settings and configurations
- Value:
- Clean, professional interface
- Clear project status and progress
- Efficient upload and management tools
- Easy export functionality
Annotators (Mobile App Users)
- Not relevant for this development scope
- Use separate mobile application
- Complete the actual annotation tasks
- Important context: Understanding their workflow helps in designing the web interface that manages their work
Secondary Stakeholders
Product Team
- Senior Frontend Engineer (Jordan): Code review and technical guidance
- Backend Engineer (Jordan): Provides APIs and infrastructure
- Product Manager (Frank): Defines features and priorities
Business Goals
- Create an efficient platform for managing annotation projects
- Provide clear visibility into annotation progress
- Enable smooth data upload and management
- Ensure professional, trustworthy experience for data owners
Impact on Development
- Focus on data owner experience
- Prioritize project management and monitoring features
- Design clear status indicators and progress metrics
- Build efficient upload and file management interfaces
- Ensure professional, business-focused UI using shadcn/ui components
- Consider that outputs will be used by annotators, but annotation interface is not in scope
Development Workflow
Code Review Schedule
- Code reviews happen 3 times per week during optional meetings:
- Monday
- Wednesday
- Friday
- During these sessions, you can:
- Walk through your code
- Get immediate feedback
- Discuss any challenges
- Ask questions
- Plan next steps
Repository Access & Code Review
- You have direct commit access to the repository (unsorted-ai/web-app)
- Senior frontend engineer reviews code during scheduled sessions
- Feel free to continue pushing commits between review sessions
Branch Strategy
- Main branch is protected
- Create feature branches from main using format:
feature/brief-description - For bug fixes, use:
fix/brief-description - Keep commits focused and atomic
Development Flow
- Write code in your feature branch
- Test locally to ensure no obvious issues
- Push commits to your branch
- Join the next review session to discuss changes
- Address any feedback from the review
- Once approved, changes will be merged to main
Commit Guidelines
- Write clear commit messages describing what and why
- Keep commits focused on single changes where possible
- Follow conventional commits format:
feat: add project card component
Between Reviews
- Continue development on your features
- Document any questions or discussion points for next review
- Flag any blocking issues via email/chat - don’t wait for review meeting
- Push commits as you complete work - no need to wait for review sessions
Key Requirements
Development Standards
- TypeScript for all new code
- Follow Next.js 14 app router best practices
- Implement URL statefulness for all interactive elements
- Use Server Components by default, Client Components only when necessary
- Maintain responsive design (mobile + desktop)
Core Features
-
Authentication
- Implement Supabase authentication
- Support OAuth and magic link options
- Handle session persistence
-
Layout
- Responsive header with logo, theme toggle, and profile
- Collapsible sidebar with nested navigation
- Consistent layout across all pages
-
Project Management
- Dashboard with paginated project cards
- Project creation workflow
- Detailed project view with tabs
- File upload system with progress tracking
UI/UX Focus Points
- Implement loading states using suspense boundaries
- Add skeleton loaders for async content
- Ensure smooth transitions between states
- Handle empty states with clear CTAs
- Show upload progress and status indicators
File Handling
- Image upload via Supabase Storage
- Maximum file size: 4MB per image
- Implement file type validation
- Show upload progress and preview
Git Workflow
- Feature branch workflow
- Clear, descriptive commit messages
- Pull requests for feature merges
Initial Development Approach
- Set up Next.js 15 project with TypeScript
- Install and configure shadcn/ui components
- Implement layout and navigation structure
- Build authentication flow
- Create dashboard with placeholder data
- Implement project creation flow
- Build project detail page with tabs
- Add file upload functionality
API Integration
- API response shapes are provided in the requirements
- Initially build with placeholder data matching API schema
- Real API integration will follow UI completion
Development Priorities
- UI/UX implementation with placeholder data
- Component structure and responsiveness
- Navigation and state management
- File upload functionality
- Authentication integration
Not Required for MVP
- Advanced caching strategies
- Complex state management solutions
- Performance optimizations
- Analytics integration
Code Quality Expectations
- Type-safe implementations
- Consistent component patterns
- Clear separation of server/client components
- Proper error handling