Add in a quote from the movie the Big Lebowski or Forest Gump
...
Less code is better: Choose solutions that involve less custom code or reduce code where possible Simpler for AI Agent: choose solutions that are simpler for the AI agent, less likely for it to make mistakes. solo developer Context: This project is built and maintained by a single developer. Prioritize: Proven technologies Use well-established existing libraries, frameworks, and patterns instead of custom code where possible. Minimal dependencies Avoid over-engineering for a 1-person team Clear documentation Write code that's easy to understand and modify later. Add single-line comments to explain major code sections Gradual scaling Start simple, optimize later when needed Feel free to provide additional feedback, guidance if you see issues with the current design or code.
Infrastructure: The entire application runs on Vercel infrastructure, including hosting, serverless functions, and database connections. Please see RUNBOOK.md for more information.
Events are the main entities (e.g., "2024 Presidential Election") Markets belong to events (e.g., "Will Trump win the election?") Predictions are AI-generated outcomes for specific markets Users authenticate via Privy and have predictions and watchlists Categories use enum for consistent categorization (elections, geopolitics, etc.) Tags provide flexible labeling via many-to-many relationship with events
All privileged endpoints require Privy authentication. (client and server-side) Server-side auth validation on all privileged API endpoints CSP headers configured for development and production environments
OpenRouter API for multiple AI model access
If the development server port localhost:3000 is already in use, please do not try to start another development server automatically. Ask first before starting another development server.
See package.json for the most recent commands.
Prefer to use and write queries in lib/db/queries/ for all database operations.
Follow existing patterns: snake_case for DB columns, camelCase for TypeScript
Use transactions for multi-step operations
Use database indexes for common query patterns
Follow the project's .cursorrules for consistent development:
Use TypeScript with strict typing Functional components with hooks preferred Follow Next.js 15 App Router patterns Use shadcn/ui components for consistency
Components: components/ (reusable) and app/ (page-specific)
Client only code: /components/client
Server only code: /components/server
Shared: /components/shared
Services: lib/services/ for business logic
Database: lib/db/ for queries and schema
Types: lib/types.ts for shared interfaces
Utils: lib/utils.ts for helper functions
Use Next.js API routes in app/api/
Include proper error handling and logging
Use appropriate HTTP status codes
Validate all inputs and implement proper authentication
Use pnpm run db:migrate: commands where possible.
Migration naming: Provide --name descriptive_name to avoid interactive prompts. Example pnpm run db:migrate:dev --name add_user_table
Use pnpm not npm: Project uses pnpm for package management and build commands
Prisma Externalization: Use serverExternalPackages: ['@prisma/client'] in next.config.mjs for Next.js 15+
Avoid Build-Time Imports: Never import from Prisma runtime libraries at module level to prevent webpack errors
Test Both Build & Runtime: Always run pnpm run build and pnpm test --run after Prisma-related changes
Keep Config Simple: Prefer Next.js built-in externalization over complex webpack configurations
Migration Pattern: After schema changes, run pnpm prisma generate to regenerate the client with JSON protocol
Never make direct Prisma calls in components or API routes
Validate all user inputs Sanitize data before database operations Never expose API keys or secrets in client code Start with basic security Add advanced features as needed
Polymarket API: Market and event data (via polymarket-client.ts)
OpenRouter API: AI model access (via openrouter-client.ts)
Privy: User authentication
generate-batch-predictions.ts: Bulk prediction generation
generate-single-prediction.ts: Individual market predictions
market-research-service.ts: Web research for predictions
prediction-checker.ts: Validation and accuracy tracking
updatePolymarketEventsAndMarketData.ts: Data synchronization
GET /api/markets List markets with search/filtering
POST /api/predict Generate AI prediction (authenticated)
GET /api/predictions/recent Recent predictions (authenticated)
GET /api/events List events with markets
POST /api/run-data-pipeline Manual data pipeline trigger (authenticated)
Use try-catch blocks with proper error logging
Return structured error responses using ApiResponse type
Include meaningful error messages for debugging
Log errors appropriately for monitoring
Keep error handling simple Don't over-engineer for edge cases
Suggest caching strategies for frequently accessed data Use database transactions for multi-step operations Monitor API performance and implement rate limiting
If you write test cases, try to write lightweight or flexible test cases for critical paths as the schemas and code are changing frequently. Reuse existing test harnesses and code where possible.
Legal Compliance: Always describe as "analysis tool" not "financial advisor"
Environment Variables: Use .env.local (not .env), update .env.example for new variables. Never pull down production environment variables automatically. Always ask the user for specific values if production env vars are needed. Use development environment variables by default: vercel env pull .env.local --environment=development
solo developer Approach: Prefer simple, maintainable solutions over complex architectures
After completing any significant task or making changes to the codebase, Proactively suggest relevant next steps that might be helpful based on the work just completed. This could include: Related improvements or enhancements Testing recommendations Security considerations Performance optimizations Integration opportunities Code organization improvements
Collapsible Content with Gradient Fade: For long text content that needs to be collapsed, use gradient fade effects to indicate there's more content below Show More/Less Controls: Use chevron icons (ChevronDown/ChevronUp) with descriptive text for expand/collapse actions Consistent Collapsed Heights: Match collapsed heights to related UI sections (e.g., prediction summary height) Add a data-debug-id attribute to html elements to help identify them properly. Consistency: Always use the same spacing values across similar elements Breathing room: Generous spacing prevents cramped layouts and improves readability Visual hierarchy: Larger spacing between major sections, smaller spacing within sections Responsive: Tailwind spacing classes automatically scale appropriately on mobile
Refer to /lib/design-system.ts for instructions.
Build and Runtime errors: if you find or are given build or runtime errors, try first to consider whether the error is tied to a deeper system design issue or whether it is a small tactical issue. If there is a bigger design issue, please stop and share this information with user for their feedback. Prefer fat services for writes (transactions, idempotency), thin for reads.