smartprocure · sadasant · May 25, 2018 · May 25, 2018 · May 25, 2018 · May 25, 2018
diff --git a/README.md b/README.md
@@ -1,2 +1,88 @@
-# contexture-docs
-Documentation for Contexture
+# Contexture Documentation
+
+This repo is designed to host the documentation of Contexture as a
+whole. Everythin we currently have here is **WORK IN PROGRESS**.
+
+## Table of Contents
+
+- [About Contexture](about/README.md)
+  - [What is Contexture](about/what-is-contexture.md)
+  - [Glossary of Terms](about/glossary-of-terms.md)
+  - [Map of Repos](about/map-of-repos.md)
+  - [Brief History](about/brief-history.md)
+  - [Alternatives & Benchmarks](about/alternatives-benchmarks.md)
+- [Getting Started](getting-started/README.md)
+  - [Project Setup](getting-started/setup.md)
+    - [Install Node 9 and NPM](getting-started/setup.md#installing-node-9-and-npm)
+    - [Install Contexture](getting-started/setup.md#installing-contexture)
+    - [Install Contexture Client](getting-started/setup.md#installing-contexture-client)
+    - [Install Contexture ElasticSearch](getting-started/setup.md#installing-contexture-elasticsearch)
+    - [Install Contexture Mongo](getting-started/setup.md#installing-contexture-mongo)
+    - [Install Contexture React](getting-started/setup.md#installing-contexture-react)
+  - [A First Contexture Script](getting-started/first-script.md)
+  - [Connecting to Elasticsearch & MongoDB](getting-started/connecting.md)
+    - [Connecting to ElasticSearch](getting-started/connecting.md#connecting-to-elasticsearch.md)
+    - [Connecting to MongoDB](getting-started/connecting.md#connecting-to-mongodb.md)
+  - [Connecting to Other Databases](getting-started/connecting-other-databases.md)
+  - [Simple Search Box](getting-started/simple-search-box.md)
+  - [Your First Filter](getting-started/your-first-filter.md)
+  - [Discovering the Database](getting-started/discovering-the-database.md)
+  - [IMDB Index](getting-started/imdb-example.md)
+- [Querying](querying/README.md)
+  - [Contexture DSL](querying/contexture-dsl.md)
+  - [Interactive Queries](querying/interactive-queries/README.md)
+    - [Contexture Client](querying/interactive-queries/contexture-client.md)
+      - [Initializing the Contexture Client](querying/interactive-queries/contexture-client.md#initializing-the-contexture-client)
+      - [Context Tree](querying/interactive-queries/contexture-client.md#context-tree)
+      - [Tree and getNode](contexture-client.md#tree-and-getnode)
+      - [Mutate, Add and Remove](contexture-client.md#mutate-add-and-remove)
+    - [Introduction to Reactors](querying/interactive-queries/reactors.md)
+- [Types and Type Components](types/README.md)
+  - [DIY Types](types/diy-types.md)
+    - [How to Write a Provider Type](types/diy-types.md#how-to-wite-a-provider-type)
+    - [How to Write a Client Type](types/diy-types.md#how-to-wite-a-client-type)
+    - [How to Write a UI Component for a Type](types/diy-types.md#how-to-write-a-ui-component-for-a-type)
+    - [The Example Types](types/diy-types.md#the-example-types)
+  - [ElasticSearch Example Types](types/elasticsearch-example-types.md)
+  - [Mongo Example Types](types/mongo-example-types.md)
+  - [Available React Components for Types](types/react-components.md)
+- [Other Components](other-components/README.md)
+  - [Generally Useful Components](other-components/general.md)
+  - [Layout Components](other-components/layout.md)
+- [Managing State](managing-state/README.md)
+  - [DIY State Management](managing-state/diy.md)
+  - [MobX](managing-state/mobx.md)
+  - [Redux (Coming Soon)](managing-state/redux.md)
+- [Theming](theming/README.md)
+- [Recommendations](recommendations/README.md)
+  - [Architecture](recommendations/architecture.md)
+    - [Client vs Server](recommendations/architecture.md#client-vs-server)
+    - [Type definitions](recommendations/architecture.md#type-definitions)
+    - [Scaling](recommendations/architecture.md#scaling)
+  - [Server Side Searches](recommendations/server-side-searches.md)
+    - [Searching On an Endpoint](recommendations/server-side-searches.md#searching-on-an-endpoint)
+    - [Caching](recommendations/server-side-searches.md#caching)
+  - [Client Side Searches](recommendations/client-side-searches.md)
+    - [Click to Search](recommendations/client-side-searches.md#click-to-search)
+    - [Real Time Searches](recommendations/client-side-searches.md#real-time-searches)
+    - [Cascading](recommendations/client-side-searches.md#cascading)
+- [Under the Hood](under-the-hood/README.md)
+  - [Design Principles](under-the-hood/design-principles.md)
+  - [Contexture Core](under-the-hood/contexture-core.md)
+    - [Default Export](under-the-hood/contexture-core.md#default-export)
+    - [The Algorithm](under-the-hood/contexture-core.md#the-algorithm)
+    - [Utility Functions](under-the-hood/contexture-core.md#utility-functions)
+  - [Contexture Providers](under-the-hood/contexture-providers/README.md)
+    - [Contexture ElasticSearch](under-the-hood/contexture-providers/)
+    - [Contexture Mongo](under-the-hood/contexture-providers/)
+    - [Building Your Own Provider](under-the-hood/contexture-providers/building-your-own-provider.md)
+  - [Contexture Client](under-the-hood/contexture-client.md)
+    - [State Properties](under-the-hood/contexture-client.md#state-properties)
+    - [Lenses](under-the-hood/contexture-client.md#lenses)
+    - [Reactors in Detail](under-the-hood/contexture-client.md#reactors-in-detail)
+    - [Serialization](under-the-hood/contexture-client.md#serialization)
+    - [Traversals](under-the-hood/contexture-client.md#traversals)
+  - [Contexture React](under-the-hood/contexture-react.md)
+- [Examples](examples/README.md)
+- [Contributing Guide](contributing-guide/README.md)
+- [License](LICENSE)
diff --git a/about/README.md b/about/README.md
@@ -0,0 +1,10 @@
+[↩  Parent: Table of Contents](../README.md)
+
+# About Contexture
+
+Table of Contents:
+- [What is Contexture](what-is-contexture.md)
+- [Glossary of Terms](glossary-of-terms.md)
+- [Map of Repos](map-of-repos.md)
+- [Brief History](brief-history.md)
+- [Alternatives & Benchmarks](alternatives-benchmarks.md)
diff --git a/about/alternatives-benchmarks.md b/about/alternatives-benchmarks.md
@@ -0,0 +1,8 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: Brief History](brief-history.md)
+
+# Alternatives & Benchmarks
+
+    TODO
+
+[↪ Next: Getting Started](../getting-started/README.md)
diff --git a/about/brief-history.md b/about/brief-history.md
@@ -0,0 +1,8 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: Map of Repos](map-of-repos.md)
+
+# Brief History
+
+    TODO
+
+[↪ Next: Alternatives & Benchmarks](alternatives-benchmarks.md)
diff --git a/about/glossary-of-terms.md b/about/glossary-of-terms.md
@@ -0,0 +1,92 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: What is Contexture](what-is-contexture.md)
+
+# Glossary of Terms
+
+## Contexture
+
+> NOUN
+> 1. The fact or manner of being woven or linked together to form a
+> connected whole.  
+> 1.1. A mass of things interwoven together; a fabric.  
+> 1.2. The putting together of words and sentences in connected
+> composition; the construct of a text.  
+> 1.3. A connected literary structure; a continuous text.
+
+[Source](https://en.oxforddictionaries.com/definition/us/contexture).
+
+## Domain-Specific Language (DSL)
+
+> A domain-specific language (DSL) is a computer language specialized
+> to a particular application domain. This is in contrast to a
+> general-purpose language (GPL), which is broadly applicable across
+> domains.
+
+[Source](https://en.wikipedia.org/wiki/Domain-specific_language).
+
+## Search Query
+
+According to Wikipedia, `Search Query`, in the context of the `web`, refers to:
+
+> ...a query that a user enters into a web search engine to satisfy his or her
+> information needs. Web search queries are distinctive in that they are often
+> plain text or hypertext with optional search-directives (such as "and"/"or"
+> with "-" to exclude). They vary greatly from standard query languages, which
+> are governed by strict syntax rules as command languages with keyword or
+> positional parameters.
+
+[Source](https://en.wikipedia.org/wiki/Web_search_query).
+
+## Faceted Search
+
+> Faceted search, also known as faceted navigation or faceted browsing, is a
+> technique used by eCommerce brands to help users analyze, organize, and
+> filter large sets of product inventory based on filters such as size, color,
+> price, and brand.
+
+[Source](https://www.dynamicyield.com/glossary/faceted-search/).
+
+> Faceted search, also called faceted navigation or faceted browsing, is a
+> technique for accessing information organized according to a faceted
+> classification system, allowing users to explore a collection of information
+> by applying multiple filters. A faceted classification system classifies each
+> information element along multiple explicit dimensions, called facets,
+> enabling the classifications to be accessed and ordered in multiple ways
+> rather than in a single, pre-determined, taxonomic order.
+
+[Source](https://en.wikipedia.org/wiki/Faceted_search).
+
+## Search Filter
+
+> An extension of faceted search, a search filter is a specific product
+> attribute a visitor can use to refine the search results of a particular
+> category listing, e.g. by size, color, price, or brand. Multiple filters may
+> be applied to take a broad range of products and refine them into a more
+> narrow selection, allowing the end user to retrieve the most relevant search
+> results based on the criteria they’ve selected.
+
+[Source](https://www.dynamicyield.com/glossary/search-filter/).
+
+## Configuration Based Development
+
+> The difference between configuration-driven development and model-driven
+> development is that the former is not restricted to the model of the code
+> such as classes, fields, and relationships. Configuration-driven development
+> (CCD) encompasses anything that can be configured within your application.
+> For example, if your architecture dictates that particular business rules
+> must be applied consistently across your application, you can use
+> configuration files to configure and apply those rules.
+
+[Source](https://www.ibm.com/developerworks/library/wa-configdev/index.html).
+
+## Functional Logic Programming
+
+> Functional logic programming is the combination, in a single programming
+> language, of the paradigms of functional programming (including higher-order
+> programming) and logic programming (nondeterministic programming,
+> unification). This style of programming is embodied by various programming
+> languages, including Curry and Mercury.
+
+[Source](https://en.wikipedia.org/wiki/Functional_logic_programming).
+
+[↪ Next: Map of Repos](map-of-repos.md)
diff --git a/about/map-of-repos.md b/about/map-of-repos.md
@@ -0,0 +1,69 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: Glossary of Terms](glossary-of-terms.md)
+
+# Map of Repos
+
+The Contexture framework comes to life through a list of repositories
+that individually specialize in some needed layer for our
+architecture. We will be using most (if not all) of these projects in
+our upcoming pages. Let's explore the repos we have so far:
+
+## Contexture Core
+
+[github.com/smartprocure/contexture](https://github.com/smartprocure/contexture)
+is where our main DSL processor lives. It is a very small layer that
+ties everything together. This one receives the information about the
+different search representations, about the databases involved, and
+the DSL, then outputs the search results respective to each one of the
+queries described in a copy of the received DSL.
+
+You can read more about the core here:
+- [In the repository](https://github.com/smartprocure/contexture).
+- In our [docs about querying (Contexture Core section)](../querying/contexture-core.md).
+- Or with greater detail in our [under the hood docs (Contexture Core section)](../under-the-hood/contexture-core.md).
+
+## Contexture Providers
+
+The Contexture Providers are the interfacing layer that ties the
+Contexture DSL to the targeted databases. So far, we have only two
+open source providers:
+
+- [contexture-elasticsearch](https://github.com/smartprocure/contexture-elasticsearch),
+  and
+- [contexture-mongo](https://github.com/smartprocure/contexture-mongo).
+
+If you are planning to use either ElasticSearch or MongoDB for your
+project, the best way to get started is to use those repositories.
+However, if you need to use Contexture with another database, you will
+need to implement the provider yourself. We're looking for code
+contributors, so please don't feel limited to the current available
+tools. Help us grow together!
+
+You can read more about Contexture Providers here:
+- In our [docs about querying (Available Providers section)](../querying/available-providers.md).
+- In with greater detail in our [under the hood docs (Contexture Providers section)](../under-the-hood/contexture-providers/README.md).
+
+## Contexture Client
+
+The Contexture Client is responsible for triggering behaviors on the
+search interfaces by knowing what causes changes in one or more
+elements of the search tree. It is the key piece of technology that
+allows our search interfaces to work in real time.
+
+You can read more about the Contexture Client here:
+- [In the repository](https://github.com/smartprocure/contexture-client).
+- In our [docs about querying (Contexture Client section)](../interactive-queries/contexture-client.md).
+- Or with greater detail in our [under the hood docs (Contexture Client section)](../under-the-hood/contexture-client.md).
+
+## Contexture React
+
+The Contexture React repository holds a list of components that
+facilitate building search interfaces. They are mainly graphical
+representations of the types that exist on our Contexture Providers.
+
+You can read more about the Contexture React:
+- [In the repository](https://github.com/smartprocure/contexture-client).
+- In our guide for the [Available React Components for Types](./types/react-components.md).
+- Or in greater detail in our [under the hood docs (Contexture React section)](under-the-hood/contexture-react.md).
+
+[↪ Next: Brief History](brief-history.md)
diff --git a/about/what-is-contexture.md b/about/what-is-contexture.md
@@ -0,0 +1,53 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: About Contexture](README.md)
+
+# What Is Contexture
+
+People of the Internet, here we officialy introduce you to
+`contexture`, our framework for building search interfaces.
+
+This framework is carefully designed to be a generic solution for a
+universe of unlimited possible search interfaces. We've started with a
+minimal set of repositories that are representative of tools that
+empower our business, but are intended to be merely examples. If
+anything, our approaches are only use cases, for the potential of
+this tool is ultimately yours to take.
+
+A quick search over the Internet would reveal that the word
+`contexture` means: `the fact or manner of being woven or linked
+together to form a connected whole` and also `the putting together of
+words and sentences in connected composition; the construction of a
+text`.
+
+Picking `contexture` as the name for this project means that we are
+trying to expose not only our ultimate intentions, but also more or
+less how the system is built. The way our projects work is by a DSL
+that is used to gather different intended search inputs, each one
+representing some useful abstraction of a search filter (like an input
+where you can write a word to be searched, or another where you can
+filter the search results by one or more options), then using the
+values to process a DSL that will end up retrieving values from one or
+more different databases, then returning these values on the
+respective sections of the DSL, so that each result can update each
+one of the components of the user interface. A more detailed
+description is visible in the following diagram.
+
+<p align="center"><img src="https://i.imgur.com/L96DVYh.png" /></p>
+
+The canonical example of a Contexture Node is faceted search, where
+you have a checkbox list that is both a filter (in the sense that it
+restricts results based on the checked values) and an aggregation
+(which shows the top n values that can be checked). Contexture allows
+them to be nested in advanced searches with boolean joins like
+`and`/`or`/`not`.
+
+<p align="center"><img src="https://i.imgur.com/jmU8WuP.png" /></p>
+
+This thought process will become more clear as we progress through the
+docs. Hopefully, some pages later it will be easy to grasp how we
+provide a new perspective on building search interfaces, and perhaps
+even how you can use it to power up your business, just like we have
+been doing for almost a decade.
+
+[↪ Next: Glossary of Terms](glossary-of-terms.md)  
+[↪ Or perhaps you want to jump to: Map of Repos](map-of-repos.md)
diff --git a/getting-started/README.md b/getting-started/README.md
@@ -0,0 +1,21 @@
+[↩  Parent: Table of Contents](../README.md)
+
+# Getting Started
+
+Table of Contents:
+- [Project Setup](setup.md)
+  - [Install Node 9 and NPM](setup.md#installing-node-9-and-npm)
+  - [Install Contexture](setup.md#installing-contexture)
+  - [Install Contexture Client](setup.md#installing-contexture-client)
+  - [Install Contexture ElasticSearch](setup.md#installing-contexture-elasticsearch)
+  - [Install Contexture Mongo](setup.md#installing-contexture-mongo)
+  - [Install Contexture React](setup.md#installing-contexture-react)
+- [A First Contexture Script](first-script.md)
+- [Connecting to Elasticsearch & MongoDB](connecting.md)
+  - [Connecting to ElasticSearch](connecting.md#connecting-to-elasticsearch.md)
+  - [Connecting to MongoDB](connecting.md#connecting-to-mongodb.md)
+- [Connecting to Other Databases](connecting-other-databases.md)
+- [Simple Search Box](simple-search-box.md)
+- [Your First Filter](your-first-filter.md)
+- [Discovering the Database](discovering-the-database.md)
+- [IMDB Index](imdb-example.md)
diff --git a/getting-started/connecting-other-databases.md b/getting-started/connecting-other-databases.md
@@ -0,0 +1,17 @@
+[↩  Parent: Table of Contents](../README.md)  
+[↩  Previous: Connecting to Elasticsearch & MongoDB](connecting.md)
+
+## Connecting to Other Databases
+
+Contexture depends on it's providers to be able to know how to
+translate from the Contexture DSL to the specific DSL that each
+database needs. Because of this, to connect to other databases you
+will need to create a new Provider.
+
+If you want to build your own provider, please follow this detailed
+guide: [Building Your Own
+Provider](../under-the-hood/contexture-providers/building-your-own-provider.md).
+Beware that it might get into the core of contexture, which is not
+needed if you can take advantage of the existing providers.
+
+[↪ Next: Simple Search Box](simple-search-box.md)