​

Repository Map

​

Status

• document type: current state
• source of truth: the checked-out onelink application repository plus the docs/ submodule and local Codex skill library
• use this page when the question is “where does this thing live?” or “which repo should I edit?”

​

Repository Set

OneLink currently operates across four local knowledge and change surfaces:

1. onelink
   • the main Rails/Vue application repository
2. onelink/docs
   • the Mintlify documentation repository mounted into the app repo as a git submodule
3. onelink/.codex/skills
   • the versioned project copy of the OneLink skill family
4. $CODEX_HOME/skills
   • the installed local Codex skill library used by the runtime agent in this workspace

Practical rule:

• product code, migrations, routes, jobs, services, and tests belong to onelink
• docs content, docs navigation, Mintlify config, and local OpenAPI docs belong to onelink/docs
• versioned Codex skill definitions belong to onelink/.codex/skills
• installed Codex runtime skills belong to $CODEX_HOME/skills

​

Main Application Repository

The main application repository is a Rails monolith extended by the OneLink fork, with several major code surfaces.

​

Top-Level Directories

• app/
  • Rails controllers, models, services, jobs, views, policies, presenters, and frontend code
• enterprise/
  • inherited technical overlay that extends or overrides core behavior
• config/
  • routes, initializers, environment config, feature flags, AI tool config, Sidekiq, Puma, storage, and other runtime settings
• db/
  • migrations and current schema
• spec/
  • request, controller, model, service, and enterprise test coverage
• swagger/
  • OpenAPI source fragments plus generated JSON output
• deployment/
  • legacy VM/systemd/nginx deployment assets
• docker/ and docker-compose*.yaml
  • container build and local deployment setup
• docs/
  • mounted docs submodule

​

Frontend Surfaces

Frontend code is primarily under app/javascript/:

• dashboard/
  • main agent-facing application UI
• widget/
  • embedded chat widget UI
• portal/
  • help center / article portal UI
• survey/
  • CSAT and survey surfaces
• sdk/
  • client SDK-related frontend assets
• superadmin_pages/
  • super admin UI
• shared/
  • shared helpers and components across frontend surfaces

​

Backend Surfaces

Backend code is primarily split like this:

• controllers:
  • app/controllers/api/, app/controllers/public/, app/controllers/platform/, app/controllers/super_admin/, app/controllers/webhooks/
• services:
  • app/services/ with many feature and provider subfolders
• models:
  • app/models/ plus feature namespaces such as channel/, integrations/, and scheduling/
• jobs and listeners:
  • app/jobs/ and app/listeners/
• policies and presenters:
  • app/policies/ and app/presenters/

​

Operational Control Files

These files are the main runtime and build control points:

• Procfile.dev-lite
  • Rails + Vite local development without Sidekiq
• Procfile.dev
  • Rails + Sidekiq + Vite full local development
• docker-compose.yaml
  • local Docker-based environment
• vite.config.mts
  • frontend bundling and alias behavior
• tailwind.config.js
  • Tailwind tokens and utility config
• config/routes.rb
  • application route surface
• config/features.yml
  • feature flags and product capabilities
• config/agents/tools.yml
  • Captain/custom tool registry
• config/initializers/01_inject_enterprise_edition_module.rb
  • enterprise extension mechanism

​

Documentation Repository

The docs repository is mounted at:

• docs/

Key parts:

• docs.json
  • Mintlify navigation and site config
• *.mdx
  • human and agent-readable docs pages
• openapi/
  • local OpenAPI JSON files consumed by Mintlify API reference
• scripts/sync-openapi-from-onelink.sh
  • sync helper that copies OpenAPI output from the app repo
• AGENTS.md
  • docs-specific agent rules

Use Docs Repository Workflow for commit and sync rules.

​

Project Skill Source

The versioned project copy of the OneLink skill family lives under:

• onelink/.codex/skills

This copy should be committed with the project when skill behavior changes. Current skill families stored there are:

• onelink-builder
• onelink-backend
• onelink-frontend
• onelink-api
• onelink-integrations
• onelink-captain
• onelink-documentation
• onelink-deployment

​

Installed Skill Library

The local Codex skill library currently lives under:

• $CODEX_HOME/skills
• typically ~/.codex/skills if CODEX_HOME is not customized

OneLink-specific skills are split into:

• onelink-builder
  • top-level coordinator skill
• onelink-backend
  • Rails/backend implementation surface
• onelink-frontend
  • Vue/dashboard/widget/portal/survey/sdk surface
• onelink-api
  • API contracts and Swagger/OpenAPI surface
• onelink-integrations
  • channels, providers, hooks, and external integrations
• onelink-captain
  • Captain/copilot/documents/custom tools/AI surface
• onelink-documentation
  • Mintlify docs, docs structure, docs repo workflow
• onelink-deployment
  • self-hosted deployment and runtime operations
• onelink-gitops
  • GitHub flow, submodule updates, skill sync, and upstream sync

Use Skill Map for when to invoke each skill.

​

Skill Sync Rule

Use the project script:

• ./.codex/scripts/sync-skills.sh to-codex-home

to copy the versioned project skills into the installed Codex skill directory.

​

Where To Edit By Task

​

Backend Feature

Edit mostly in:

• app/models/
• app/services/
• app/controllers/
• config/routes.rb
• spec/
• swagger/ if API behavior changes

Always search enterprise/ for companion code first.

​

Frontend Feature

Edit mostly in:

• app/javascript/dashboard/
• app/javascript/widget/
• app/javascript/portal/
• app/javascript/survey/
• app/javascript/shared/

Check components-next/, existing routes, and current stores before adding new structures.

​

API Contract

Edit mostly in:

• controllers and builders/serializers
• request specs
• swagger/
• onelink/docs/openapi/ after sync

​

Docs Change

Edit mostly in:

• onelink/docs/*.mdx
• onelink/docs/docs.json
• onelink/docs/openapi/*

Commit the docs change in the docs repository first.

​

Deployment Change

Edit mostly in:

• deployment/
• docker/
• docker-compose*.yaml
• config/environments/
• config/puma.rb
• config/sidekiq.yml
• docs/self-hosted/

​

Reading Order For New Tasks

Use this reading order before editing:

1. code in app/, enterprise/, config/, db/, and spec/
2. Current Architecture
3. Repository Map
4. the relevant execution guide under contributing-guide/
5. the relevant skill in onelink/.codex/skills
6. the installed runtime copy in $CODEX_HOME/skills if you need to confirm what Codex is currently loading

If docs and code disagree, trust the code.