A modern web application for processing and managing emails with client tracking.
- Email fetching and processing
- Client management
- Domain tracking
- Form type classification
- Real-time updates
- Modern UI with responsive design
- Frontend: Next.js 14 with App Router, React, TypeScript, Tailwind CSS
- Backend: Supabase (PostgreSQL, Authentication, Real-time subscriptions)
- Email Processing: Gmail API
- State Management: TanStack Query (React Query)
- UI Components: Shadcn/ui
- Forms: React Hook Form with Zod validation
- Testing: Jest, React Testing Library
- CI/CD: GitHub Actions
src/
├── app/ # Next.js app router pages
├── components/ # React components
│ ├── ui/ # Reusable UI components
│ ├── emails/ # Email-related components
│ ├── clients/ # Client management components
│ └── forms/ # Form-related components
├── lib/ # Shared utilities
│ ├── supabase/ # Supabase client and types
│ ├── gmail/ # Gmail API integration
│ └── utils/ # Helper functions
├── hooks/ # Custom React hooks
├── types/ # TypeScript type definitions
└── styles/ # Global styles and Tailwind config
supabase/
├── migrations/ # Database migrations
└── types/ # Generated Supabase types
tests/ # Test files
- Clone the repository
- Install dependencies:
npm install - Copy
.env.exampleto.env.localand fill in the environment variables - Run database migrations:
npm run migrate - Start the development server:
npm run dev
Create a .env.local file with the following variables:
# Database
DATABASE_URL=your_database_url
# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_tokenRun migrations:
npm run migrateStart the development server:
npm run devRun tests:
npm testThe application is automatically deployed via GitHub Actions when changes are pushed to the main branch.
The application includes a script to automatically process recent emails from Gmail. The script:
- Fetches unprocessed emails from Gmail
- Downloads and processes attachments
- Converts PDFs to images for viewing
- Updates email tracks (WOTC Machine or Forms Admin)
- Applies Gmail labels based on tracks
- Install dependencies:
npm install- Set up environment variables:
- Copy
.env.local.exampleto.env.local - Fill in the required values:
- Supabase URL and service role key
- Google OAuth credentials (client ID, secret, refresh token)
- PDF server URL if running locally
- Run the script:
npm run process-emailsThe script can be set up to run automatically using a cron job or a task scheduler:
# Example cron job (runs every 5 minutes)
*/5 * * * * cd /path/to/project && /usr/local/bin/npm run process-emailsIf you encounter issues:
- Check the environment variables are set correctly
- Ensure the Google OAuth tokens are valid
- Verify the Supabase connection is working
- Check the PDF server is running if processing PDFs
For detailed error messages, check the console output when running the script.
- Create a feature branch
- Make your changes
- Run tests
- Submit a pull request
MIT License