project-architecture

Use this skill to understand the RingCentral App Connect project structure, including the monorepo layout, core package APIs, handlers, models, and how components interact.

1.16x

Quality

43%

Does it follow best practices?

Impact

100%

1.16x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agent-skills/project-architecture/SKILL.md

Project Architecture

Name: project-architecture
Rating: 64 (1 reviews)
Author: ringcentral

Repository Structure

rc-unified-crm-extension/
├── packages/                    # Monorepo packages
│   ├── core/                    # @app-connect/core - shared business logic
│   │   ├── handlers/            # Business logic handlers
│   │   ├── models/              # Sequelize data models
│   │   ├── lib/                 # Utilities (jwt, analytics, logger, etc.)
│   │   ├── connector/           # Connector registry
│   │   └── mcp/                 # MCP (Model Context Protocol) tools
│   ├── cli/                     # CLI tools for project setup
│   └── template/                # Template for new connector projects
├── src/                         # Main development server
│   ├── connectors/              # CRM connector implementations
│   ├── plugins/                 # Data plugins
│   ├── index.js                 # App entry point
│   ├── server.js                # Express server
│   └── lambda.js                # AWS Lambda handler
├── serverless-deploy/           # Production deployment
├── serverless-deploy-test/      # Test environment deployment
├── docs/                        # Documentation (MkDocs)
└── tests/                       # Integration tests

Core Package (@app-connect/core)

Entry Point Usage

const { createCoreApp, connectorRegistry } = require('@app-connect/core');

// Set manifest before registering connectors
connectorRegistry.setDefaultManifest(manifest);
connectorRegistry.registerConnector('myCRM', myCRMConnector, manifest);

// Create Express app with all core functionality
const app = createCoreApp();

Handlers (packages/core/handlers/)

Handler	File	Purpose
Auth	`auth.js`	OAuth flow, token refresh, API key auth
Contact	`contact.js`	Contact search, matching, creation
Log	`log.js`	Call/message logging, updates
Admin	`admin.js`	Admin settings, user mappings
User	`user.js`	User settings, preferences
Disposition	`disposition.js`	Call dispositions

Models (packages/core/models/)

Model	File	Purpose
UserModel	`userModel.js`	User auth, tokens, settings
CallLogModel	`callLogModel.js`	Call log records
MessageLogModel	`messageLogModel.js`	SMS/message logs
AdminConfigModel	`adminConfigModel.js`	Admin configurations
CacheModel	`cacheModel.js`	Caching layer

Key Libraries (packages/core/lib/)

Library	File	Purpose
JWT	`jwt.js`	Token encoding/decoding
Analytics	`analytics.js`	Usage tracking
Logger	`logger.js`	Structured logging
Constants	`constants.js`	Shared constants (LOG_DETAILS_FORMAT_TYPE, etc.)
CallLogComposer	`callLogComposer.js`	Compose call log details
ErrorHandler	`errorHandler.js`	Standardized error handling
Util	`util.js`	General utilities

Connector Registry

The connector registry manages CRM connector lifecycle:

const { connectorRegistry } = require('@app-connect/core');

// Register a connector
connectorRegistry.registerConnector('platformName', connectorModule, manifest);

// Register interface functions (extend without modifying original)
connectorRegistry.registerConnectorInterface('platformName', 'createCallLog', customFn);

// Get composed connector
const connector = connectorRegistry.getConnector('platformName');

API Routes

Core routes provided by @app-connect/core:

Authentication

GET /authValidation - Validate auth
GET /oauth-callback - OAuth callback
POST /apiKeyLogin - API key login
POST /unAuthorize - Logout

Contacts

GET /contact - Find by phone
POST /contact - Create contact
GET /custom/contact/search - Search by name

Logging

GET /callLog - Get call log
POST /callLog - Create call log
PATCH /callLog - Update call log
PUT /callDisposition - Set disposition
POST /messageLog - Create message log

Settings

GET /user/settings - User settings
POST /user/settings - Update user settings
GET /admin/settings - Admin settings
POST /admin/settings - Update admin settings

Environment Variables

Key environment variables:

# Database
DATABASE_URL=postgres://...
DISABLE_SYNC_DB_TABLE=false

# Server
APP_SERVER_SECRET_KEY=secret
HASH_KEY=hash-key
IS_PROD=false

# DynamoDB (local dev)
DYNAMODB_LOCALHOST=http://localhost:8000

# CRM-specific (example for Pipedrive)
PIPEDRIVE_CLIENT_ID=...
PIPEDRIVE_CLIENT_SECRET=...
PIPEDRIVE_ACCESS_TOKEN_URI=...
PIPEDRIVE_REDIRECT_URI=...

Development Workflow

# Start local server
npm run server

# Start ngrok tunnel
npm run ngrok

# Run tests
npm test

# Build for deployment
npm run build

# Deploy
npm run deploy

Database

Development: SQLite (db.sqlite)
Production: PostgreSQL via Sequelize ORM
Cache/Locks: DynamoDB (local via npm run dynamo-local)

Repository: ringcentral/rc-unified-crm-extension
Commit: f59d4a2

Last updated: 6 days ago
Created: 6 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.