Skip to main content

Coginiti Flow: Analytics Development Lifecycle

This document describes the standard user workflow for building, reviewing, publishing, and consuming analytics in Coginiti. Coginiti Flow is analogous to GitFlow (conceptually similar, not identical) and is centered on Coginiti’s internal Analytics Catalog.


1) Core concepts​

Analytics Catalog

  • System of record for projects and files.
  • Provides automatic versioning on save, diff, and rollback.
  • Enables secure sharing and co-editing in real time.

Project

  • Fundamental unit of work in Coginiti.
  • Contains code, assets, and project configuration.
  • Organized into folders and files.

Workspaces

  • Personal Workspace: user’s sandbox for initial development, scratch work, and private projects.
  • Shared Workspace: shared space where projects can be shared for collaboration.

Project Hub

  • Read or run only repository of approved (blessed) analytics and transformations (think Maven or npm).
  • Publishes projects with semantic versioning, descriptions, change log.
  • Source for consumption and forking.

Roles (functional)

  • Owner/Editor: creates and edits projects.
  • Reviewer: provides project and line level feedback, approves or requests changes.
  • Publisher: user who holds the Publisher permission and can release an approved project to the Project Hub.

Permissions model

  • Personal Workspace

    • Owner: each user is the owner of any project in their personal workspace.
  • Shared Projects

    • Viewer: can read/run assets in the project
    • Editor: can edit any assets in the project
    • Co-Owner: can edit any assets in the project and invite other collaborators
  • Project Hub

    • Viewer: can read/run assets in the project
    • Publisher: can publish projects to the Project Hub

2) Project structure​

Every project includes two base configuration files at the repository root:

  • project.toml (project runtime configuration)

    • Connection targets and runtime profiles
    • Execution parameters (environment settings)
    • Dependency declarations (if applicable)
  • linter.toml (custom coding and style rules)

    • Rule definitions and severities
    • Formatting and naming conventions
    • Exception rules

Projects may include domain folders (for example, sources/, base/, marts/, tests/, docs/) and any other structure required by the team. Files are automatically versioned when saved to the Analytics Catalog.


3) Flow overview (at a glance)​

  1. Initialize in Personal Workspace
  2. Share to Shared Workspace collaborators via the Analytics Catalog
  3. Develop with automatic versioning and real time co-editing
  4. Submit for Review and select Reviewers and a Publisher
  5. Review (project and line level feedback, notifications)
  6. Address Feedback and resubmit as needed
  7. Approve by Reviewers
  8. Publish to the Project Hub by a Publisher
  9. Consume from the Project Hub (read or run only)
  10. Fork from the Project Hub to begin new changes

4) Detailed lifecycle​

A. Initialize (Owner)​

  • Create a Project in your Personal Workspace.
  • Add project.toml and linter.toml.
  • Establish folder structure and initial files.

Outcomes

  • Project exists in the Catalog with first saved version.

B. Share (Owner)​

  • Share the project with specific users or groups within the organization.
  • Shared users can view or edit per granted permissions.

Outcomes

  • Collaborators have access, and co-editing is active when appropriate.

C. Develop (Owner plus collaborators)​

  • Edit files. Each save creates a new file version in the Analytics Catalog.
  • Use diff to compare versions and rollback if needed.
  • Enable co-editing so multiple users can work on the same file in real time.
  • Run and validate logic as required by the project.

Outcomes

  • Working draft with traceable change history.

D. Submit for Review (Owner)​

  • Submit the project for review.
  • Select Reviewers and a Publisher (user with the Publisher permission).
  • The system sends notifications to selected Reviewers.

Outcomes

  • Project enters In Review state.

E. Review and Feedback (Reviewers)​

  • Review at both project and line level.
  • Leave feedback items. These are visible to the Owner and collaborators.
  • Approve or request changes.
  • Owners receive notifications about required fixes.

Outcomes

  • Either Approved or Changes Requested.

F. Address Feedback (Owner)​

  • Resolve comments, update files, and resubmit for review.
  • Version history captures all edits made during rework.

Outcomes

  • Project returns to In Review until approved.

G. Publish (Publisher)​

  • When approved, a user with the Publisher permission publishes the project to the Project Hub.
  • The system assigns a semantic version.

Outcomes

  • Project becomes available in the Project Hub for read or run usage.

H. Consume and Reuse (All users)​

  • Users discover and run published projects from the Project Hub.
  • The Hub is read or run only. No direct edits are allowed.

Outcomes

  • Consistent analytics and transformations consumed across the organization.

I. Fork to Innovate (Owner)​

  • To modify a published project, fork it from the Project Hub.
  • A new editable copy is created in the Owner’s workspace.
  • Repeat the lifecycle for the next change set.

Outcomes

  • New work begins with a clear provenance link to the published version.

5) States and transitions​

StateDescriptionEntered ByExited ByNext States
DraftEditable project in Personal or Shared WorkspaceOwnerSubmit for ReviewIn Review
In ReviewUnder active review with notificationsOwner (by submission)Approve or Request ChangesApproved, Changes Requested
Changes RequestedReviewers requested fixesReviewersResubmit for ReviewIn Review
ApprovedReviewers approved current revisionReviewersPublishPublished
PublishedRead or run only in Project Hub with semantic versionPublisherForkDraft

Transition rules

  • Only Reviewers can move a project to Approved or Changes Requested.
  • Only a Publisher can move an Approved project to Published.
  • Only Owner (or Editors) can Fork published projects.

---|---|---|---|---| | Draft | Editable project in Personal or Org Workspace | Author | Submit for Review | In Review | | In Review | Under active review with notifications | Author (by submission) | Approve or Request Changes | Approved, Changes Requested | | Changes Requested | Reviewers requested fixes | Reviewers | Resubmit for Review | In Review | | Approved | Reviewers approved current revision | Reviewers | Publish | Published | | Published | Read or run only in Project Hub with semantic version | Publisher | Fork | Draft |

Transition rules

  • Only Reviewers can move a project to Approved or Changes Requested.
  • Only a Publisher can move an Approved project to Published.
  • Only Authors (or Editors) can Fork published projects.

6) Versioning and release management​

File versioning

  • Every save to the Catalog creates a new file version.
  • Authors and collaborators can view diffs and roll back as needed.

Project publishing versioning

  • Published projects use Semantic Versioning: MAJOR.MINOR.PATCH.
    • Increment MAJOR for backward incompatible changes.
    • Increment MINOR for backward compatible features.
    • Increment PATCH for backward compatible bug fixes.

Deprecation guidance

  • Deprecate older project versions in the Hub once consumers have migrated.
  • Communicate deprecation timelines and upgrade notes in project docs.

7) Collaboration, reviews, and notifications​

  • Co-editing: multiple users can edit the same file in real time.
  • Line level and project level feedback: reviewers annotate specific lines and leave overall comments.
  • Notifications: reviewers are notified on submission; authors are notified on requested changes and approvals.
  • Traceability: the Catalog maintains a complete history of edits and discussions.

8) Governance and quality​

  • Project Hub governance: The Project Hub is fully governed. Administrators set the initial structure and assign Publisher or Viewer permissions.
  • linter.toml encodes coding rules and conventions.
  • Review checklist (suggested): naming, structure, performance, security, documentation, tests or validations as applicable.
  • Publishing gate: only projects that pass review can be released to the Project Hub.

9) Mapping to GitFlow (conceptual)​

  • Personal or Shared Workspace Draft is similar to a feature branch.
  • Submit for Review is similar to a pull request.
  • Approved plus Publish is similar to merge to main plus release.
  • Project Hub plays the role of a versioned package repository.
  • Fork from the Hub is similar to branching from a released tag to begin a new change set.

10) Checklists​

Author: before submit

  • project.toml and linter.toml are present and valid
  • Lint issues resolved
  • Docs and usage notes updated
  • Tests or validations run (if applicable)

Reviewer: during review

  • Standards compliance per linter.toml
  • Correctness and performance
  • Security and data access controls
  • Documentation completeness

Publisher: before publish

  • Review status is Approved
  • Release notes captured
  • Semantic version chosen and recorded

11) FAQ​

Can I edit a published project directly? No. Published projects in the Project Hub are read or run only. Fork the project to make changes.

How do I undo a bad edit during development? Use file rollback in the Analytics Catalog to revert to a previous version.

Who selects the version number when publishing? The Publisher confirms the semantic version based on the nature of the changes.

What happens to reviewers’ comments after publication? They remain part of the project’s review history for traceability.


12) Visual reference (lifecycle)​

[Draft (Personal/Org WS)]
|
v submit for review
[In Review] <----- resubmit ----- [Changes Requested]
|
v approve
[Approved]
|
v publish (Publisher)
[Published: Project Hub]
|
v fork
[Draft]

13) Visual Reference (lifecycle)​

@startuml
hide empty description
skinparam shadowing false

state "Draft (Personal/Shared WorkSpace)" as Draft
state "In Review" as InReview
state "Changes Requested" as ChangesRequested
state "Approved" as Approved
state "Published (Project Hub)" as Published

Draft --> InReview : submit for review (Owner)
InReview --> Approved : approve (Reviewers)
InReview --> ChangesRequested : request changes (Reviewers)
ChangesRequested --> InReview : resubmit (Owner/Editor)
Approved --> Published : publish (Publisher)
Published --> Draft : fork (Owner/Editor)

note right of Published
Read or run only
Semantically versioned
end note

@enduml