From 5144ed13fb6d164451187901aa77784ae2fd8f91 Mon Sep 17 00:00:00 2001
From: Viktor Varland <viktor@dhis2.org>
Date: Mon, 21 Jun 2021 12:25:48 +0200
Subject: [PATCH] docs(architecture): update component structure

---
 ARCHITECTURE.md                               | 22 +++++++++++++++++++
 .../modal/src/modal/modal.stories.e2e.js      |  4 +---
 components/modal/src/modal/modal.stories.js   |  4 +---
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index bbef9dd2b0..e05806ffee 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -72,6 +72,28 @@ This means that:
 > and may have breaking changes without us bumping the major version on
 > `@dhis2/ui-*` components.
 
+Each component package has a logical and semantic scope, that may group
+related components.
+
+If needed, components can be extracted to distinct component packages to
+break e.g. circular dependencies or to provide a tighter scope.
+
+If UI is fully decomposed, every single component would be its own
+package, and this would not be a problem. We may end up there in the
+future, but for now we are striking a pragmatic balance between packages
+and components.
+
+To make extraction easier, each component package has a
+`{component}/src/index.js` file that defines the exported components for that
+package.
+
+If a package contains multiple components, then each subcomponent should have a
+`index.js` file that defines its module boundary. This makes it easier to
+extract it in the future: {component}/src/{subcomponent}/index.js`.
+
+Components should import from the `index.js` files and avoid reaching into
+non-exported parts of a component.
+
 #### Collections
 
 In UI terms a collection is a set of components, and is considered the
diff --git a/components/modal/src/modal/modal.stories.e2e.js b/components/modal/src/modal/modal.stories.e2e.js
index 64643ec159..abf835efae 100644
--- a/components/modal/src/modal/modal.stories.e2e.js
+++ b/components/modal/src/modal/modal.stories.e2e.js
@@ -1,9 +1,7 @@
 import { Button, ButtonStrip } from '@dhis2-ui/button'
 import { storiesOf } from '@storybook/react'
 import React, { useState } from 'react'
-import { ModalActions } from '../index.js'
-import { ModalContent } from '../index.js'
-import { ModalTitle } from '../index.js'
+import { ModalActions, ModalContent, ModalTitle } from '../index.js'
 import { Modal } from './modal.js'
 
 window.onClose = window.Cypress && window.Cypress.cy.stub()
diff --git a/components/modal/src/modal/modal.stories.js b/components/modal/src/modal/modal.stories.js
index 9b4c0405de..215908289e 100644
--- a/components/modal/src/modal/modal.stories.js
+++ b/components/modal/src/modal/modal.stories.js
@@ -2,9 +2,7 @@ import { Button, ButtonStrip } from '@dhis2-ui/button'
 import { SingleSelect, SingleSelectOption } from '@dhis2-ui/select'
 import { sharedPropTypes } from '@dhis2/ui-constants'
 import React, { useState } from 'react'
-import { ModalActions } from '../index.js'
-import { ModalContent } from '../index.js'
-import { ModalTitle } from '../index.js'
+import { ModalActions, ModalContent, ModalTitle } from '../index.js'
 import { Modal } from './modal.js'
 
 const description = `