WEBAPP

Overview

Codaro is a modern developer productivity analytics platform that provides real-time coding insights, team collaboration tools, and AI-powered project management. This documentation is designed for developers and engineering managers who want to understand the architecture, deploy the application self-hosted, or contribute to the codebase.

Technology Stack

Frontend

  • Framework: Next.js 15.3.2 with App Router

  • Language: TypeScript 5.3.3

  • UI Library: React 19.1.1

  • Styling: Tailwind CSS 4.1.11

  • Component Library: HeroUI 2.8.3 (modern React component system)

  • Icons: Lucide React + React Icons

  • Animations: Framer Motion 12.23.6

  • Charts: ECharts 5.6.0 + Recharts 2.15.3

Backend

  • Runtime: Node.js (Next.js API Routes)

  • Database: MySQL with Prisma ORM 6.13.0

  • Authentication: Firebase Authentication 11.10.0

  • Admin SDK: Firebase Admin 13.4.0

  • Payments: Stripe 18.4.0

  • Email: Nodemailer 7.0.5

  • Storage: Firebase Storage

Development Tools

  • Testing: Playwright 1.54.2

  • Linting: ESLint 9.0.0

  • Package Manager: npm

Key Benefits

  • Modern Stack: Built with the latest stable versions of Next.js and React

  • Type Safety: Full TypeScript implementation for better developer experience

  • Performance: Server-side rendering, static generation, and optimized bundling

  • Scalability: Modular architecture with clear separation of concerns

  • Security: Firebase Authentication with JWT tokens and role-based access control

Architecture Overview

High-Level Architecture

Codaro follows a modern full-stack architecture with clear separation between frontend, backend, and data layers:

┌─────────────────────────────────────────────────────────────┐
│                     Client Layer                             │
│  Next.js App Router + React Components + Tailwind CSS       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   API Layer (Next.js Routes)                 │
│  Authentication • Teams • Reports • Integrations • Billing   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   Service Layer                              │
│  Firebase Auth • Stripe • Processing Modules • Email         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   Data Layer                                 │
│  MySQL Database (Prisma ORM) • Firebase Storage             │
└─────────────────────────────────────────────────────────────┘

Directory Structure

codaro-webapp/
├── src/
│   ├── app/              # Next.js App Router pages and API routes
│   ├── components/       # Reusable React components
│   ├── lib/             # Core libraries and utilities
│   ├── hooks/           # Custom React hooks
│   ├── contexts/        # React Context providers
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Helper functions
├── prisma/              # Database schema and migrations
├── public/              # Static assets
└── docs/                # Documentation files

Data Flow

  1. User Authentication: Firebase handles user authentication with JWT tokens

  2. API Requests: Client components make requests to Next.js API routes

  3. Data Processing: API routes interact with Prisma ORM for database operations

  4. Real-time Updates: The system aggregates signals from various data sources

  5. Response: Processed data is returned to the client for rendering

Key Modules

Dashboard (Live Feed)

Purpose: Presents real-time team status and productivity metrics.

Features:

  • Real-time activity monitoring

  • Team member status indicators

  • Project progress tracking

  • Activity timeline visualization

Technical Implementation:

  • Aggregates signals from multiple API endpoints

  • Uses processing modules to analyze coding patterns

  • Implements efficient data caching for performance

  • Displays data using interactive ECharts visualizations

Security Note: The dashboard uses proprietary algorithms to process and present data. Implementation details are abstracted into processing modules.

Teams & Roles

Purpose: Manages team structure, member roles, and permissions.

Features:

  • Team creation and management

  • Role-based access control (Programmer/Manager)

  • Member invitation system

  • Team settings and preferences

Data Model (High-Level):

  • Users belong to Teams through membership relationships

  • Each membership has an associated Role (Programmer or Manager)

  • Teams can have multiple members with different permission levels

  • Invitation system tracks pending team joins

API Endpoints:

  • /api/teams - Team CRUD operations

  • /api/teams/[teamId]/members - Member management

  • /api/teams/[teamId]/invitations - Invitation handling

Integrations

Purpose: Connects external development tools to Codaro.

Supported Integrations:

  • GitHub: Commit tracking and repository analysis

  • Jira (Beta): Task synchronization

  • Linear (Planned): Issue tracking integration

How It Works:

  • OAuth-based authentication with external services

  • Webhook receivers for real-time updates

  • Data synchronization modules that map commits to tasks

  • Secure credential storage using encrypted tokens

Integration Flow:

  1. User authorizes Codaro to access their GitHub/Jira account

  2. System stores encrypted access tokens

  3. Webhooks notify Codaro of new commits/tasks

  4. Processing modules correlate commits with project tasks

  5. Analytics dashboard displays integrated data

API Endpoints:

  • /api/github/* - GitHub integration handlers

  • /api/jira/* - Jira integration handlers

  • /api/webhooks/* - Webhook receivers

Reports & Billing

Purpose: Generate AI-powered reports and manage subscriptions.

Reports Module:

  • Automated report generation based on team activity

  • AI-powered insights and recommendations

  • Customizable report templates

  • Export functionality (PDF, CSV)

Billing Module:

  • Stripe-powered subscription management

  • Multiple pricing tiers (Free, Pro)

  • Seat-based billing for teams

  • Trial period management

  • Invoice generation and payment history

Subscription Tiers:

  • Free Plan: Up to 2 team members, basic analytics

  • Pro Plan: Unlimited members, advanced analytics, integrations, priority support

API Endpoints:

  • /api/personal-reports - Report generation

  • /api/billing/* - Subscription management

  • /api/webhooks/stripe - Stripe webhook handler

Analytics Engine

Purpose: Process and analyze developer activity data.

Components:

  • Data collection from IDE plugins

  • Activity aggregation and normalization

  • Pattern recognition modules

  • Productivity metrics calculation

Data Sources:

  • IDE activity (typing, file changes, debugging)

  • Git commits and branches

  • Task management systems

  • Time tracking data

Security: All processing happens server-side. Code content is never stored, only metadata and activity patterns.

Environment Configuration

Codaro requires several environment variables to function properly. Create a .env file in the root directory with the following variables.

Required Variables

Database Configuration

# MySQL database connection string
DATABASE_URL="mysql://username:password@host:port/database"

Setup Instructions:

  • Use MySQL 8.0 or higher

  • Create a dedicated database for Codaro

  • Ensure the user has full permissions on the database

Firebase Configuration (Authentication & Storage)

# Firebase Client SDK (Public)
NEXT_PUBLIC_FIREBASE_API_KEY="<YOUR_FIREBASE_API_KEY>"
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN="<YOUR_PROJECT>.firebaseapp.com"
NEXT_PUBLIC_FIREBASE_PROJECT_ID="<YOUR_PROJECT_ID>"
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET="<YOUR_PROJECT>.appspot.com"
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID="<YOUR_SENDER_ID>"
NEXT_PUBLIC_FIREBASE_APP_ID="<YOUR_APP_ID>"
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID="<YOUR_MEASUREMENT_ID>"

# Firebase Admin SDK (Server-side)
FIREBASE_PROJECT_ID="<YOUR_PROJECT_ID>"
FIREBASE_CLIENT_EMAIL="<YOUR_SERVICE_ACCOUNT_EMAIL>"
FIREBASE_PRIVATE_KEY="<YOUR_PRIVATE_KEY>"

Setup Instructions:

  1. Create a Firebase project at https://console.firebase.google.com

  2. Enable Authentication with Email/Password and Google providers

  3. Enable Firebase Storage for file uploads

  4. Generate a service account key for Admin SDK

  5. Copy the configuration values to your .env file

Security Note: Never commit the .env file to version control. The FIREBASE_PRIVATE_KEY should be kept secure.

Stripe Configuration (Payments)

# Stripe API Keys
STRIPE_SECRET_KEY="sk_test_<YOUR_SECRET_KEY>"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_<YOUR_PUBLISHABLE_KEY>"

# Stripe Price IDs
PRICE_PRO_MONTHLY="price_<YOUR_MONTHLY_PRICE_ID>"
PRICE_PRO_YEARLY="price_<YOUR_YEARLY_PRICE_ID>"

# Stripe Webhook Secret
STRIPE_WEBHOOK_SECRET="whsec_<YOUR_WEBHOOK_SECRET>"

Setup Instructions:

  1. Create a Stripe account at https://stripe.com

  2. Create products and pricing in the Stripe Dashboard

  3. Set up webhook endpoint: https://yourdomain.com/api/webhooks/stripe

  4. Copy the webhook signing secret

Note: Use test keys for development and live keys for production.

Email Configuration (Optional)

# Email service configuration
EMAIL_FROM="[email protected]"
EMAIL_HOST="smtp.gmail.com"
EMAIL_PORT="587"
EMAIL_USER="<YOUR_EMAIL>"
EMAIL_PASSWORD="<YOUR_APP_PASSWORD>"

Setup Instructions:

  • Configure an SMTP server or use a service like SendGrid, Mailgun, or Gmail

  • For Gmail, create an App Password in your Google Account settings

Application Configuration

# Application URL
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Node Environment
NODE_ENV="development"

Optional Variables

# Google OAuth (if using Google Sign-In)
GOOGLE_CLIENT_ID="<YOUR_CLIENT_ID>"
GOOGLE_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

# GitHub Integration
GITHUB_CLIENT_ID="<YOUR_CLIENT_ID>"
GITHUB_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

# Jira Integration (Beta)
JIRA_CLIENT_ID="<YOUR_CLIENT_ID>"
JIRA_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

Environment Variable Checklist

Before running the application, ensure you have configured:

Installation & Setup

Prerequisites

  • Node.js: Version 20.11.0 or higher

  • npm: Version 9.0.0 or higher

  • MySQL: Version 8.0 or higher

  • Git: For version control

1

Clone the repository

git clone <repository-url>
cd codaro-webapp
2

Install dependencies

npm install

This will install all required packages defined in package.json.

3

Configure environment variables

  1. Create a .env file in the root directory

  2. Copy the environment variables from the Environment Configuration section

  3. Replace all placeholder values with your actual credentials

Important: Never use production credentials in development environments.

4

Set up the database

Generate Prisma Client:

npm run db:generate

Run database migrations:

npm run db:migrate

This will:

  • Create all necessary database tables

  • Set up relationships and indexes

  • Apply any pending migrations

Alternative: If you want to push schema without migrations:

npm run db:push
5

Start the development server

npm run dev

The application will be available at http://localhost:3000.

6

Verify installation

  1. Open your browser and navigate to http://localhost:3000

  2. You should see the Codaro landing page

  3. Try creating an account to verify Firebase authentication

  4. Check the console for any error messages

Database Setup

Database Schema Overview

Codaro uses MySQL with Prisma ORM for type-safe database access. The schema includes several interconnected models:

Core Entities (High-Level):

  • Users: Store user profiles and authentication data

  • Teams: Represent development teams

  • Memberships: Link users to teams with specific roles

  • Projects: Track coding projects and repositories

  • Activity Data: Store developer activity metrics (abstracted)

  • Subscriptions: Manage billing and payment information

  • Integrations: Store OAuth tokens for external services

Relationships:

  • Users can belong to multiple Teams

  • Teams have multiple Members with different Roles

  • Projects are associated with Teams

  • Activity data is linked to Users and Projects

  • Subscriptions are tied to Teams

Database Migrations

Codaro uses Prisma Migrate for version-controlled schema changes.

Create a new migration:

npm run db:migrate

View database in Prisma Studio:

npm run db:studio

This opens a web interface at http://localhost:5555 where you can view and edit database records.

Database Backup

Recommended backup strategy:

  1. Use MySQL's native backup tools (mysqldump)

  2. Schedule regular automated backups

  3. Store backups in a secure, off-site location

  4. Test backup restoration periodically

Example backup command:

mysqldump -u username -p database_name > backup_$(date +%Y%m%d).sql

Performance Considerations

  • Indexes: The schema includes optimized indexes for common queries

  • Connection Pooling: Prisma automatically manages connection pooling

  • Query Optimization: Use Prisma's query optimization features

  • Caching: Implement Redis or similar for frequently accessed data (optional)

Deployment

Production Build

Build the application for production:

npm run build

This creates an optimized production build in the .next directory.

Start Production Server

npm start

The server will run on port 3000 by default.

Deployment Platforms

Vercel (Recommended)

Vercel is the recommended platform as it's built by the creators of Next.js.

Steps:

  1. Push your code to GitHub, GitLab, or Bitbucket

  2. Import the project in Vercel Dashboard

  3. Configure environment variables in Vercel settings

  4. Deploy automatically on every push

Environment Variables: Add all variables from your .env file to Vercel's environment settings.

Docker Deployment

Create a Dockerfile:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

Build and run:

docker build -t codaro-webapp .
docker run -p 3000:3000 --env-file .env codaro-webapp

Traditional VPS/Server

Requirements:

  • Ubuntu 20.04+ or similar Linux distribution

  • Node.js 20+ installed

  • MySQL 8.0+ installed

  • Nginx for reverse proxy (recommended)

  • SSL certificate (Let's Encrypt recommended)

Steps:

  1. Clone the repository on your server

  2. Install dependencies: npm install

  3. Configure environment variables

  4. Build the application: npm run build

  5. Use PM2 to manage the process: pm2 start npm --name "codaro" -- start

  6. Configure Nginx as a reverse proxy

  7. Set up SSL with Certbot

Example Nginx configuration:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Post-Deployment Checklist

Security Considerations

Authentication & Authorization

  • Firebase Authentication: Provides secure user authentication with industry-standard practices

  • JWT Tokens: Used for API authentication with automatic expiration

  • Role-Based Access Control: Users have specific roles (Programmer/Manager) with different permissions

  • Session Management: Secure session handling with automatic timeout

Data Protection

  • Encryption in Transit: All data transmitted over HTTPS/TLS

  • Encryption at Rest: Sensitive data encrypted in the database

  • API Key Security: All API keys stored as environment variables, never in code

  • OAuth Tokens: External service tokens encrypted before storage

Best Practices

  1. Never commit .env files to version control

  2. Use strong passwords for database and admin accounts

  3. Regularly update dependencies to patch security vulnerabilities

  4. Implement rate limiting on API endpoints (built-in)

  5. Monitor logs for suspicious activity

  6. Use HTTPS in production environments

  7. Validate all user inputs (implemented via Zod schemas)

  8. Implement CORS policies appropriately

Privacy Compliance

  • GDPR Compliant: User data handling follows GDPR guidelines

  • Data Minimization: Only necessary data is collected

  • Right to Deletion: Users can request data deletion

  • Data Export: Users can export their data

  • Transparent Privacy Policy: Clear communication about data usage

Code Security

  • No Source Code Storage: Only metadata and activity patterns are stored

  • Secure Processing: All analytics processing happens server-side

  • Access Controls: Strict access controls on sensitive operations

  • Audit Logging: Important actions are logged for security audits

API Overview

Codaro provides a comprehensive RESTful API built on Next.js API Routes.

Authentication

All API requests (except public endpoints) require authentication via Firebase JWT token.

Headers:

Authorization: Bearer <firebase_jwt_token>

Core API Endpoints

Authentication

  • POST /api/auth/signup - Create new user account

  • POST /api/auth/login - Authenticate user

  • POST /api/auth/logout - End user session

  • GET /api/current-user - Get current authenticated user

Teams

  • GET /api/teams - List user's teams

  • POST /api/teams - Create new team

  • GET /api/teams/[teamId] - Get team details

  • PUT /api/teams/[teamId] - Update team

  • DELETE /api/teams/[teamId] - Delete team

  • GET /api/teams/[teamId]/members - List team members

  • POST /api/teams/[teamId]/members - Add team member

  • DELETE /api/teams/[teamId]/members/[userId] - Remove member

Reports

  • GET /api/personal-reports - Get user's reports

  • POST /api/personal-reports - Generate new report

  • GET /api/personal-reports/[reportId] - Get specific report

Billing

  • POST /api/billing/create-checkout-session - Create Stripe checkout

  • POST /api/billing/create-portal-session - Access billing portal

  • GET /api/billing/subscription - Get subscription status

Integrations

  • GET /api/github/authorize - Start GitHub OAuth flow

  • POST /api/github/webhook - GitHub webhook receiver

  • GET /api/jira/authorize - Start Jira OAuth flow

  • POST /api/jira/webhook - Jira webhook receiver

Activity Data

  • POST /api/heartbeats - Submit activity data from IDE plugins

  • GET /api/user-totals - Get user activity totals

  • GET /api/user_stats - Get detailed user statistics

Rate Limiting

API endpoints implement rate limiting to prevent abuse:

  • Authentication endpoints: 5 requests per minute

  • Data submission endpoints: 100 requests per minute

  • Query endpoints: 60 requests per minute

Error Handling

API responses follow standard HTTP status codes:

  • 200 - Success

  • 201 - Created

  • 400 - Bad Request

  • 401 - Unauthorized

  • 403 - Forbidden

  • 404 - Not Found

  • 429 - Too Many Requests

  • 500 - Internal Server Error

Error Response Format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Troubleshooting

Common Issues

Database Connection Errors

Problem: Can't connect to MySQL server

Solutions:

  1. Verify DATABASE_URL in .env is correct

  2. Ensure MySQL server is running

  3. Check firewall settings allow connections

  4. Verify database user has proper permissions

Firebase Authentication Errors

Problem: Firebase configuration is incomplete

Solutions:

  1. Verify all NEXT_PUBLIC_FIREBASE_* variables are set

  2. Check Firebase project settings match your configuration

  3. Ensure Firebase Authentication is enabled in Firebase Console

  4. Verify API key restrictions in Google Cloud Console

Build Errors

Problem: Module not found or Type errors

Solutions:

  1. Delete node_modules and .next directories

  2. Run npm install again

  3. Clear npm cache: npm cache clean --force

  4. Ensure Node.js version is 20.11.0 or higher

Stripe Webhook Failures

Problem: Webhooks not being received or processed

Solutions:

  1. Verify webhook endpoint URL in Stripe Dashboard

  2. Check STRIPE_WEBHOOK_SECRET matches Stripe configuration

  3. Ensure your server is publicly accessible (use ngrok for local testing)

  4. Check webhook logs in Stripe Dashboard

Performance Issues

Problem: Slow page loads or API responses

Solutions:

  1. Enable production mode: NODE_ENV=production

  2. Optimize database queries (check slow query log)

  3. Implement caching for frequently accessed data

  4. Use Prisma query optimization techniques

  5. Monitor server resources (CPU, memory, disk)

Getting Help

If you encounter issues not covered here:

  1. Check Logs: Review application logs for error messages

  2. Database Logs: Check MySQL error logs

  3. Browser Console: Look for client-side errors

  4. Network Tab: Inspect failed API requests

  5. Documentation: Review Next.js, Prisma, and Firebase documentation

Development Tips

  • Use Prisma Studio to inspect database state: npm run db:studio

  • Enable verbose logging in development for debugging

  • Use React DevTools for component debugging

  • Test API endpoints with tools like Postman or Thunder Client

  • Monitor Firebase Console for authentication issues

Additional Resources

Official Documentation

Community & Support

  • Next.js GitHub Discussions

  • Prisma Community Slack

  • Firebase Support Forums

  • Stack Overflow (tag: nextjs, prisma, firebase)

Conclusion

This documentation provides a comprehensive overview of the Codaro Webapp architecture, setup, and deployment process. The platform is built with modern technologies and follows industry best practices for security, performance, and scalability.

For self-hosted deployments, ensure all environment variables are properly configured and follow the security guidelines outlined in this documentation. Regular updates and monitoring are recommended to maintain optimal performance and security.

Key Takeaways:

  • Modern full-stack architecture with Next.js 15 and React 19

  • Secure authentication via Firebase

  • Flexible team management with role-based access control

  • Powerful integrations with GitHub and project management tools

  • Scalable infrastructure suitable for teams of all sizes

  • Comprehensive API for custom integrations

For questions or contributions, please refer to the project repository and community channels.

PreviousVSCODE