Contributing to OneGlanse

​

Overview

​

Repository Structure

oneglanse/
├── apps/
│   ├── web/          # Main product app (Next.js + tRPC)
│   ├── agent/        # Browser automation worker (Playwright + BullMQ)
│   ├── landing/      # Marketing website
│   └── docs/         # Documentation site
├── packages/
│   ├── db/           # Database schema (Postgres + ClickHouse)
│   ├── services/     # Business logic layer
│   ├── types/        # Shared TypeScript types
│   ├── ui/           # React component library
│   ├── utils/        # Utility functions
│   └── errors/       # Error handling primitives
└── biome.json        # Code formatting config

​

Prerequisites

• Node.js 20+ (required)
• pnpm 10+ (package manager)
• Docker + Docker Compose (for infrastructure)
• Git for version control

​

Development Environment Setup

git clone https://github.com/yourusername/oneglanse.git
cd oneglanse

pnpm install

cp .env.example .env
cp apps/agent/.env.example apps/agent/.env

docker compose up -d db clickhouse redis

pnpm db:migrate

# Run all apps
pnpm dev

# Or run specific apps in separate terminals:
pnpm dev:web      # Product app on port 3000
pnpm dev:agent    # Agent worker
pnpm dev:landing  # Landing site
pnpm dev:docs     # Documentation site

​

Code Style and Conventions

​

Formatting with Biome

{
  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      ".turbo",
      ".vercel",
      "coverage"
    ]
  }
}

pnpm lint:fix

​

TypeScript Standards

• Strict mode enabled - All workspaces use strict TypeScript
• Type safety first - Avoid any, prefer unknown when type is uncertain
• Shared types - Domain types go in packages/types/src/types/
• Import extensions - Use .js extensions for ESM imports (TypeScript convention)

​

File Organization

• Colocation - Keep related files together (component + styles + tests)
• Barrel exports - Use index.ts for clean public APIs
• Naming conventions:
  • Components: PascalCase.tsx
  • Utilities: camelCase.ts
  • Types: camelCase.ts or descriptive names like agent.ts
  • Constants: UPPER_SNAKE_CASE

​

Workspace Dependencies

• Cross-workspace imports - Use workspace protocol: "@oneglanse/types": "workspace:*"
• Shared code placement:
  • Business logic → packages/services
  • Type definitions → packages/types
  • UI components → packages/ui
  • Utilities → packages/utils
  • Errors → packages/errors

​

Running Tests

# Typecheck all workspaces
pnpm typecheck

# Typecheck specific workspace
pnpm --filter @oneglanse/agent typecheck

​

Common Development Tasks

​

Database Operations

# Generate Drizzle schema files
pnpm db:generate

# Run migrations
pnpm db:migrate

# Push schema changes directly (dev only)
pnpm db:push

# Open Drizzle Studio
pnpm db:studio

​

Building Apps

# Build all workspaces
pnpm build

# Build specific workspace
pnpm --filter @oneglanse/agent build

​

Cleaning Build Artifacts

# Clean all Turbo caches and outputs
pnpm clean

​

Pull Request Process

git checkout -b feature/your-feature-name

# Format code
pnpm lint:fix

# Type check
pnpm typecheck

# Test build
pnpm build

git add .
git commit -m "feat: add support for new provider"

git push origin feature/your-feature-name

​

Finding Tasks to Work On

​

GitHub Issues

• good first issue - Great for newcomers
• help wanted - Contributions welcome
• bug - Bug fixes needed
• enhancement - Feature requests

​

Project Areas

​

Starting Points

1. Add a new AI provider - See Adding Providers guide
2. Improve error handling - Enhance packages/errors
3. Add UI components - Build reusable components in packages/ui
4. Optimize queries - Improve database performance
5. Write documentation - Help others understand the codebase

​

Community Guidelines

​

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers and help them learn
• Provide constructive feedback
• Focus on what is best for the community

​

Getting Help

• GitHub Discussions - Ask questions, share ideas
• Issues - Report bugs, request features
• Pull Requests - Review others’ code, get feedback on yours

​

Review Process

• Maintainers will review your PR
• Address feedback promptly
• Be open to suggestions
• Iterate until approval

​

Architecture Principles

​

Monorepo Best Practices

• Build dependencies - Apps depend on packages, packages can depend on each other
• Turbo caching - Turbo caches build outputs for speed
• Workspace isolation - Each package has its own package.json

​

Data Flow

1. User configures prompts in apps/web
2. Jobs submitted via packages/services → BullMQ queues
3. apps/agent workers consume jobs
4. Playwright browsers execute prompts on AI providers
5. Responses stored in Postgres/ClickHouse
6. Analysis jobs process responses into metrics
7. apps/web displays results in dashboards

​

Service Layer Pattern

• Business logic lives in packages/services
• Apps call service functions, not DB directly
• Services handle validation, orchestration, side effects
• Types define contracts between layers

​

Debugging Tips

​

Agent Development

// Enable debug mode in .env
DEBUG_ENABLED=true

// Use logger from utils
import { logger } from "@oneglanse/utils";
logger.log("Debug message");
logger.error("Error occurred", error);

​

Browser Automation

# Run with headed browser
PWDEBUG=1 pnpm dev:agent

# Slow down execution
SLOWMO=1000 pnpm dev:agent

​

Database Queries

pnpm db:studio

​

Additional Resources

• Main README - /README.md - Repository overview
• Workspace READMEs - Each apps/* and packages/* has its own README
• Type Definitions - packages/types/src/types/ - Domain models
• Provider Configs - apps/agent/src/core/providers/ - AI provider implementations

​

Questions?

1. Check the documentation
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Open a new issue with the question label