📘 n8n object conventions and folder structure¶
📓 Core object types in the n8n execution model¶
- 🧩 Nodes → Configuration objects
- 🔄 Workflows → Executable workflow objects
- 🧬 Subflows → Reusable workflow objects
📔 Naming convention for workflows and subflows¶
All workflows and subflows must follow the naming convention defined in this document to ensure consistency, traceability, platform ownership, and environment separation across the n8n ecosystem.
📑 Naming pattern¶
<Core object types>-<platform>-<env>-<object-type>-<functionality>
- <platform> identifies the business or technical platform the workflow belongs to
- <env> represents the target environment
- <object-type> represents the workflow classification
- <functionality> describes the business or technical purpose
📦 Recommendation for creating an Azure DevOps repository¶
Repo: 🧩 <Core object types>-<platform>-<env>-<object-type>-<functionality>¶
.
├── node-type-name/
| ├── standard folders and files/
| └── standard_folders_and_files.abc
└── README.md # Project overview with links to official documentation in docs/.
Table 1️⃣: Supported environments¶
| Environment | Description |
|---|---|
| dev | Development environment used for active development and experimentation. |
| test | Environment used for functional and integration testing. |
| qa | Quality assurance environment for validation and acceptance testing. |
| uat | User acceptance testing environment. |
| prod | Production environment executing live business processes. |
Table 2️⃣: Platforms¶
| Platform | Description |
|---|---|
| analitica | Data analytics and reporting workflows, including data ingestion, transformation, and metrics generation. |
| colabora | Collaboration and communication workflows, including notifications, approvals, and messaging integrations. |
| transversal | Cross-functional workflows reused across multiple platforms (e.g. email sending, retries, formatting). |
| logycalibrary | Catalog of artifacts and distribution layer. |
Table 3️⃣: Object types¶
| Object type | Description |
|---|---|
| shared | Reusable workflows providing common or technical functionality across platforms. |
| template | Reference workflows used as starting points for new implementations. |
| process | End-to-end business process workflows. |
| integration | System-to-system integration workflows between internal or external platforms. |
| monitoring | Workflows responsible for observability and operational health. |
| security | Workflows enforcing security, governance, and compliance controls. |
| alerting | Workflows generating alerts or notifications based on predefined conditions. |
Table 4️⃣: Workflow naming convention and examples¶
| Emoji | Platform | Environment | Object type | Convention name example <Core object types>-<Naming pattern> |
Description |
|---|---|---|---|---|---|
| 🧩 | transversal | dev | shared | workflow-transversal-dev-shared-http-retry | Reusable shared workflow providing common retry logic. |
| 📄 | analitica | dev | template | workflow-analitica-dev-template-ingestion-processes | Workflow template for analytics ingestion processes. |
| 🧪 | analitica | test | process | workflow-analitica-test-process-dataset-refresh | Analytics workflow refreshing datasets in test environments. |
| 📊 | analitica | prod | monitoring | workflow-analitica-prod-monitoring-pipeline-health | Monitoring workflow validating analytics pipeline health. |
| 🔄 | colabora | qa | integration | workflow-colabora-qa-integration-teams-notifications | Integration workflow sending notifications to collaboration tools. |
| 🚨 | colabora | prod | alerting | workflow-colabora-prod-alerting-failed-approvals | Alerting workflow for failed approval processes. |
| 🔐 | security | prod | security | workflow-security-prod-security-input-validation | Workflow enforcing security validations in production. |
| 🛡️ | monitoring | prod | monitoring | workflow-monitoring-prod-monitoring-execution-audit | Workflow providing execution audit and traceability. |
🗂️ Recommendations for folders according to LOGYCA standard and local development¶
🛡️ Folder Structure & Security Classification¶
-
🔓
docs/(Public Documentation)
Contains functional, user-facing, and non-sensitive documentation.
This folder may be published to a documentation portal or static website. -
🔒 All other folders (Confidential / Restricted)
Contain technical, operational, or executable artifacts that may include sensitive information.
These folders must not be published and should be accessible only to authorized personnel.
This separation enforces a security-by-design approach and reduces the risk of accidental exposure of confidential assets.
.
├── .vscode/ # VS Code tasks for virtualenv setup and Python debugging.
├── node_code_python_simulator/ # Code that simulates n8n's JSON input schemes for local execution.
│ ├── internal/ # Input conventions used by n8n.
│ ├── shared/ # Helpers, schemes, and other code to prevent repeating functions or statements.
│ └── requirements.txt # Not currently allowed on n8n Cloud.
├── nodes/
│ ├─── node-<Naming pattern>/
│ │ ├── docs/
│ │ ...
│ │ ...
│ └── README.md
├── subflows/
│ ├── subflow-<Naming pattern>/
│ │ ├── docs/ # Documentation written in Markdown of the code.
│ | | ├── CHANGELOG.md # All notable changes to this workflow are documented in this file.
│ | | ├── dependencies/
│ | | | ├── credentials.md # Credential usage and purpose.
│ | | | ├── systems.md # External systems involved.
│ | | | ├── subflows.md # Referenced workflows or subflows.
│ | | | ├── runtime.md # n8n runtime assumptions.
│ | | | ├── packages.md # Available libraries for code nodes.
│ | | | ├── triggers.md # Triggering mechanisms.
│ | | | ├── data-contracts.md # Input/output expectations.
│ | | | ├── configuration.md # Non-secret configuration.
│ | | | └── constraints.md # Operational limits and assumptions.
│ | | ├── contracts/ # Data contracts defining input/output structures and schemas.
│ | | | └── user-input-schema.md # JSON Schema defining expected user input payload structure.
│ | | | └── api-response-schema.md # JSON Schema defining standardized API response structure.
│ | | ├── rules/ # Declarative business and validation rules independent of execution.
│ | | | ├── email-validation-rules.md # Documentation of email validation rules.
│ | | | └── numeric-validation-rules.md # Numeric validation constraints (ranges, limits, thresholds).
│ | | ├── metadata-sticky-notes/ # Design-time notes embedded in the workflow (human-readable context).
│ | | | ├── decisions.md # Architectural and business decisions (lightweight ADRs).
│ | | | ├── map.md # Mapping between workflow nodes and their associated metadata files.
│ | | | └── references.md # Governance, ownership, versioning, and external references.
│ | | ├── images/ # Images of the documentation, if available.
│ | | └── README.md # Documentation index and navigation guide.
| | ├── artifacts/ # Exportable, versionable, and debuggable automation artifacts.
│ | | ├── workflows/ # Exported n8n workflows and subflows (JSON).
│ | | │ └── name_YYYYMMDD.json # Export workflow with date-based version control if needed.
│ | | ├── code-nodes/ # Code executed inside n8n Code nodes.
│ | | │ └── script.js # JavaScript file format.
│ | | │ └── script.py # Python file format.
│ | | ├── testing/ # Artifacts for validation and testing.
│ | | | ├── postman/ # Postman collections and environments.
│ | | | | └── add-user.json
│ | | | | └── get-user.json
│ | | | └─── README.md # Testing usage guide.
│ │ └── README.md # Redirect to the main documentation in docs/README.md.
├── workflows/
│ ├─── workflow-<Naming pattern>/
│ │ ├── docs/
│ │ ...
│ │ ...
└─ └── README.md
📌 This table provides documentation shortcuts. Executable artifacts (JSON, scripts) are documented through Markdown files only.