​

Development Guide

​

Getting Started

​

Initial Steps

1. Classify the work:
   • shared platform capability
   • domain-specific behavior
   • tenant-specific configuration
2. Check the architecture source of truth:
   • Domain Access Architecture
3. Search the current code paths first:
   • app/
   • enterprise/
   • existing docs and API surfaces
   • Repository Map if you need to locate the correct repo or directory before editing
   • remember that OneLink currently runs with inherited enterprise capabilities opened, so enterprise/ is a technical code split, not a separate product tier
4. Decide whether the feature should stay isolated:
   • if needed by multiple domains, move toward shared platform code
   • if needed by only one domain, keep it domain-scoped
   • if needed by one tenant, prefer config/custom attributes before new shared code
5. Keep upstream compatibility in mind:
   • minimize invasive patches in shared core code
   • prefer extension points, services, overlays, and isolated routes/screens where possible

​

Git and Pull Request Workflow

​

Branching and Remotes

• Branch from onelink-main
• Use a focused branch name such as feature/..., fix/..., chore/..., or sync/...
• Keep origin as the writable remote for OneLink work
• Treat upstream as the read-only upstream source
• Push branches to GitHub over SSH, not HTTPS

​

Default Delivery Path

git switch onelink-main
git pull origin onelink-main
git switch -c feature/<short-name>
git push -u origin feature/<short-name>

• commit on the feature branch
• push updates to origin
• open a pull request into onelink-main
• merge into onelink-main after review or maintainer verification

​

Before Submitting

• Keep platform and domain concerns separated in your changes
• Ensure all user-facing strings remain translatable
• Update docs when the product direction, architecture, or API behavior changes
• Do not push product changes to upstream
• If docs changed under onelink/docs, follow the separate docs repo flow in Docs Repository Workflow

​

Worktree Recommendation

​

Development Workflow

​

Developing a New Feature

# Create a branch in the following format:
feature/<issue-id>-<issue-name>

# Example:
feature/crm-healthcare-panel

• Follow platform vs domain layering rules
• Avoid putting domain-specific conditionals into shared code when an isolated extension point is possible
• Add accompanying tests when appropriate
• Include proper documentation when behavior or architecture changes

​

Bug Fixes or Chores

# Branch naming for bug fixes:
fix/<issue-id>-<issue-name>

# Branch naming for chores:
chore/<description>

• Describe whether the fix affects upstream-like core, shared platform behavior, or a specific domain zone
• Add appropriate test coverage if applicable
• Call out compatibility risks if the change touches shared access, APIs, or domain boundaries

​

Environment Setup

​

Speed Up Development

​

Project Setup

1. Quick Setup Guide - Step-by-step setup instructions
2. Environment Variables - Configuration options
3. Common Errors - Troubleshooting guide

​

Special App Integrations

• Telegram App Setup
• Line App Setup
• Mobile App Development

​

Architecture Expectations

• one shared platform, not multiple unrelated products
• domain zones such as healthcare and construction stay isolated from each other where possible
• generic should remain a first-class profile for broad customers
• shared CRM behavior belongs in platform code
• domain-specific fields and workflows belong in domain-scoped code
• Deal and Task should remain separate business entities
• custom attributes extend shared entities but should not replace core relationships and lifecycle state

​

Testing Your Contributions

​

Test Types

• Unit Tests: Test individual components and functions
• Integration Tests: Test component interactions
• End-to-End Tests: Test complete user workflows with Cypress

​

Running Tests

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/user_spec.rb

# Run Cypress tests
npm run cypress:open

​

Upstream Sync

• keep the fork diff intentional
• prefer extension and composition over large hard forks
• validate that shared changes still make sense for generic and domain-specific accounts
• merge upstream updates into a dedicated sync branch before bringing them back to onelink-main

​

Documentation and Translation

​

Documentation Guidelines

• Keep documentation clear and concise
• Include code examples where helpful
• Update documentation when changing functionality
• Prefer OneLink terminology over generic upstream wording in active product docs
• Use the OneLink architecture docs as the source of truth for platform/domain direction
• Follow the Docs Repository Workflow when changing onelink/docs, because docs live in a separate Git repository mounted as a submodule inside the main app repo
• Use Project Operations, AI Agent Operating Model, and Skill Map when the change affects how people or agents operate the project rather than only a feature implementation

​

Internationalization

• All user-facing text must be translatable
• Only add English strings - other languages are handled via Crowdin
• Use proper i18n keys and formatting

​

Community Guidelines

• Code of Conduct - Our community standards
• Community Guidelines - How we interact
• Security Reports - Reporting security issues

​

API Development

• OneLink APIs - API development guide
• API Documentation - Documenting APIs
• Platform APIs - Platform-level APIs

​

Recognition

​

Getting Help

• GitHub Issues: For bug reports and feature requests
• Discord Community: For real-time discussions with the core team
• Documentation: Comprehensive guides and API references
• Community Forums: Connect with other contributors