Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• README.md
• setup.sh

ThinkEx is a production-grade visual thinking environment designed to compound knowledge through notes, media, and AI conversations. As a production application rather than a demo, contributions must prioritize reliability, maintainability, and clear user value. This guide outlines the technical and community standards for contributing to the project.

Sources: CONTRIBUTING.md:7-13, README.md:16-28

Development Environment Setup

The ThinkEx project requires specific prerequisites and offers both automated and manual setup paths.

Prerequisites

• Node.js: Version 20 or higher.
• Package Manager: pnpm.
• Database: PostgreSQL (minimum v12+ or running via Docker).
• API Keys: A Google AI API key (GOOGLE_GENERATIVE_AI_API_KEY) is required for core functionality.

Sources: CONTRIBUTING.md:17-21, README.md:88-100, setup.sh:77-84

Automated Setup Script

The recommended way to start is the interactive setup.sh script. This script automates several critical tasks:

1. Environment Configuration: Creates .env from .env.example and generates a BETTER_AUTH_SECRET.
2. Database Provisioning: Starts a PostgreSQL container using Docker Compose and sets up the authenticated role.
3. Schema Initialization: Creates the auth schema, mock JWT functions for RLS, and runs Drizzle migrations.
4. Dependency Installation: Installs required packages via pnpm.

Sources: setup.sh:56-74, setup.sh:137-175, setup.sh:267-279

Technical Stack Overview

Contributors should be familiar with the following core technologies:

Category	Technology
Framework	Next.js
Styling	Tailwind CSS, Shadcn UI
Database	PostgreSQL with Drizzle ORM
Auth	Better Auth
State Management	TanStack Query, Zustand

Sources: README.md:68-74

Contribution Workflow

The project follows a standard GitHub flow for all changes.

Pull Request Process

1. Fork the repository and create a feature branch (e.g., feature/new-feature).
2. Commit changes with descriptive messages.
3. Push to your fork and open a Pull Request (PR) against the main repository.

Sources: README.md:169-175

Data Flow for Environment Setup

The following diagram illustrates the initialization flow handled by the setup.sh script to prepare the developer environment.

The script ensures all local dependencies and infrastructure are ready for development before starting the Next.js server.
Sources: setup.sh:56-320

Standards and Conduct

Code of Conduct

All participants are expected to adhere to the Contributor Covenant. Key standards include:

• Demonstrating empathy and kindness.
• Gracefully accepting constructive feedback.
• Prioritizing the community's overall well-being.
• Zero tolerance for harassment, sexualized language, or personal attacks.

Sources: CODE_OF_CONDUCT.md:11-37

Enforcement Guidelines

Community leaders enforce conduct through a tiered system of consequences:

1. Correction: Private warning and clarification.
2. Warning: Warning with consequences for continued behavior.
3. Temporary Ban: Suspension from community interaction for a period.
4. Permanent Ban: Pattern of violations leading to a permanent ban.

Sources: CODE_OF_CONDUCT.md:67-105

Security Policy

Security vulnerabilities should never be reported via public GitHub issues. Instead, contributors must email hello@thinkex.app. The project follows a 90-day grace period for security fixes before public disclosure.

Sources: SECURITY.md:5-24

Database Management

The project uses Drizzle ORM for schema management. Contributors modifying the database should use the following commands:

• pnpm db:push: Pushes schema changes directly to the database.
• pnpm drizzle-kit push --force: Used by the setup script to ensure schema alignment.

Sources: README.md:144-146, setup.sh:305-307

Conclusion

Contributing to ThinkEx involves adhering to a robust technical setup and a professional community standard. By following the automated setup path and respecting the code of conduct, contributors help maintain ThinkEx as a reliable, production-ready knowledge compounding tool.