The Four Layers of GOD CRM

The Four Layers of GOD CRM

Why This Page Matters

This is the single most important concept in GOD CRM.

Every feature, every screen, every piece of data in the system fits into one of four layers. Once you understand these layers, everything else -- modules, widgets, dashboards, tables, views -- clicks into place. If you skip this page, you will be confused later. If you read it carefully, the rest of the documentation will feel obvious.

This architecture was formally defined in ADR-044 (Module Terminology) and builds on ADR-001 (Universal Tables), ADR-003 (Spaces and Dashboards), and ADR-004 (Widget System).

The Smartphone Analogy

Before we dive in, think about your smartphone. You use it every day without thinking about its internal structure. But it actually has layers:

+------------------------------------------------------------------+
|                                                                    |
|   Your Android / iPhone has layers too:                           |
|                                                                    |
|   4. Home Screen Widgets   -- weather card, step counter, clock   |
|   3. Apps                  -- Instagram, Calendar, Notes, Maps    |
|   2. Files App             -- see all your files in a list        |
|   1. Internal Storage      -- raw bytes on disk, you never see it |
|                                                                    |
+------------------------------------------------------------------+

You never open your phone's internal storage directly. You use the Files app to browse things. You use full apps like Instagram for specific tasks. And you glance at small home screen widgets to get quick info without opening anything.

GOD CRM works exactly the same way -- but for YOUR business data.

The Four Layers

Here is the complete picture. We will go through each layer one by one.

+===================================================================+
|                    THE FOUR LAYERS OF GOD CRM                      |
+===================================================================+
|                                                                     |
|  Layer 4: WIDGET        [Chart] [Counter] [Tasks]                  |
|  (Dashboard Card)        Small cards on a Dashboard page           |
|                              |         |         |                  |
|  - - - - - - - - - - - - - -|- - - - -|- - - - -|- - - - - - - -  |
|                              |         |         |                  |
|  Layer 3: MODULE        [Calendar] [Documents] [Labs]              |
|  (Full App)              Full-page apps in the sidebar             |
|                              |         |         |                  |
|  - - - - - - - - - - - - - -|- - - - -|- - - - -|- - - - - - - -  |
|                              |         |         |                  |
|  Layer 2: UNIVERSAL     [Grid View] [Filters] [Sorting]           |
|  TABLE (Data Browser)    Spreadsheet-like table interface          |
|                              |         |         |                  |
|  - - - - - - - - - - - - - -|- - - - -|- - - - -|- - - - - - - -  |
|                              |         |         |                  |
|  Layer 1: RAW TABLE     [contacts] [tasks] [nodes]                |
|  (Hidden Storage)        Data rows in the database                 |
|                                                                     |
+===================================================================+

Each layer builds on the one below it. Data lives at the bottom (Layer 1) and is presented to you in increasingly specialized ways as you move up.

Layer 1: Raw Table (Hidden Storage)

Smartphone analogy: Your phone's internal memory. You never open it directly. The raw bytes are just sitting there, organized by the operating system.

What it is in GOD CRM:

Layer 1 is the database itself. Every piece of data in the system -- contacts, tasks, documents, workflow nodes -- is stored in two PostgreSQL tables:

• universal_tables -- defines the structure (what columns exist)
• table_rows -- holds the actual data (each row is a JSON object)

You never see Layer 1 directly. There is no screen in the UI that shows you raw database rows. It is purely the storage engine underneath everything else.

Example:

Imagine you have a table called "contacts" with these columns: name, email, phone, company. In the database, it looks something like this:

universal_tables:
  id=42, name="contacts", columns=[name, email, phone, company]

table_rows:
  table_id=42, data={"name": "Alice", "email": "alice@example.com", ...}
  table_id=42, data={"name": "Bob",   "email": "bob@company.org",   ...}
  table_id=42, data={"name": "Carol", "email": "carol@startup.io",  ...}

This is the foundation. Everything else reads from here and writes back here.

Key points:

• All data lives here, no exceptions
• The schema is flexible -- you can add columns without database migrations
• Data is stored as JSON inside rows (see ADR-001 for the full design)
• Hidden from the user interface

Layer 2: Universal Table (Data Browser)

Smartphone analogy: The Files app on your phone. It lets you browse what is stored on your device. You can see folders, sort by date, search by name. It does not change what is stored -- it just gives you a way to look at it.

What it is in GOD CRM:

Layer 2 is the spreadsheet-like interface that shows your data in rows and columns. When you click on a table name in the sidebar, you see a grid. That grid is Layer 2.

+------------------------------------------------------------------+
|  Contacts                               [+ Add Row] [Filter] [Sort]
|------------------------------------------------------------------+
|  Name        | Email               | Phone      | Company        |
|--------------|---------------------|------------|----------------|
|  Alice       | alice@example.com   | 555-0101   | Acme Corp      |
|  Bob         | bob@company.org     | 555-0102   | StartupXYZ     |
|  Carol       | carol@startup.io    | 555-0103   | Acme Corp      |
+------------------------------------------------------------------+

This is Layer 2: a table with rows, columns, filters, and sorting.

Layer 2 is only the table grid -- rows and columns, like a spreadsheet. You can filter rows, sort by any column, hide or reorder columns, and edit cells inline. But it is always a table. If you want a different experience -- a Kanban board, a calendar, a timeline -- those are Modules (Layer 3).

Example:

You open the "contacts" table. You see a grid with columns: name, email, phone, company. You can:

1. Apply filters -- show only contacts where company = "Acme Corp"
2. Sort by any column -- alphabetical by name, newest first, etc.
3. Hide columns you do not need right now
4. Edit a cell by clicking on it
5. Add a new row at the bottom

Want to see these contacts as cards on a Kanban board? Open the Kanban Module (Layer 3). Want to see them on a calendar? Open the Calendar Module (Layer 3). The data is the same -- the experience is different.

Key points:

• This is the "data browser" -- a spreadsheet-like grid for your tables
• Rows and columns with inline editing, filters, and sorting
• Reads from and writes to Layer 1
• This is where most day-to-day data entry happens
• For specialized views (Kanban, Calendar, Timeline, Gallery), use Modules (Layer 3)

Layer 3: Module (Full App)

Smartphone analogy: An installed app like Instagram, Google Calendar, or Notes. An app is purpose-built. It does not just show you raw files -- it gives you a complete, specialized experience with its own design, its own features, and its own way of working.

What it is in GOD CRM:

A Module is a full-page application that appears in the sidebar. It uses data from Layer 1 (raw tables) but presents it in a completely custom way with specialized logic, its own UI components, and features that go far beyond what a simple table view can offer.

Sidebar:
+------------------+
| My Space         |
|   > Dashboards   |  <-- Layer 4 lives here
|   > Tables       |  <-- Layer 2 lives here
|   v Modules      |  <-- Layer 3 lives here
|     - Documents  |
|     - Calendar   |
|     - Labs       |
|     - Wellness   |
|     - AI Agents  |
|     - Contacts   |
+------------------+

The difference between Layer 2 and Layer 3:

This is crucial. Layer 2 (Universal Table) shows your data in a generic way -- it works for any table. Layer 3 (Module) is a specialized application built for a specific purpose.

Think of it this way:

• Layer 2 is like viewing photos in the Files app -- you see thumbnails in a grid
• Layer 3 is like opening Instagram -- you see a feed, stories, reels, filters, comments, likes, sharing, and a hundred other features

A Module can do things a table grid never could:

• The Kanban module shows cards grouped by status with drag-and-drop between columns
• The Calendar module shows events in day/week/month views with drag-to-resize
• The Documents module has a rich text editor, file attachments, and version history
• The Labs/MindWorkflow module has a visual node editor with drag-and-drop connections between nodes
• The Timeline module displays bars on a time axis, like a Gantt chart
• The Gallery module shows image cards in a visual grid
• The AI Agents module lets you configure and chat with AI agents
• The Wellness module tracks health metrics with custom charts and goals

All of these modules store their data in Layer 1 (raw tables), but their user interfaces are completely custom.

Key points:

• Full-page application in the sidebar
• Purpose-built UI with specialized features
• Uses Layer 1 for storage but has its own logic and presentation
• Much more powerful than a table view
• Examples: Kanban, Calendar, Timeline, Gallery, Documents, Labs, Wellness, AI Agents, Contacts

Layer 4: Widget (Dashboard Card)

Smartphone analogy: A home screen widget. That small weather card, the step counter, the mini calendar on your phone's home screen. You do not open an app -- you just glance at the card and get the information you need.

What it is in GOD CRM:

A Widget is a compact card that lives on a Dashboard page. It shows a small, focused piece of information -- a chart, a number, a task list, a mini calendar. Widgets give you a quick overview without having to open anything.

+================================================================+
|                     My Dashboard                                |
|                                                                  |
|  +------------------+  +------------------+  +----------------+ |
|  | Tasks Remaining  |  | Revenue Chart    |  | Mini Calendar  | |
|  |                  |  |                  |  |                | |
|  |       12         |  |    /\    /\      |  | Mo Tu We Th Fr | |
|  |                  |  |   /  \  /  \     |  | [5] 6  7  8  9 | |
|  |  3 overdue       |  |  /    \/    \    |  | 12 13 14 15 16 | |
|  +------------------+  +------------------+  +----------------+ |
|                                                                  |
|  +------------------+  +--------------------------------------+ |
|  | New Contacts     |  | Recent Documents                     | |
|  |                  |  |                                      | |
|  |  This week: 8    |  |  - Q1 Report (edited 2h ago)        | |
|  |  This month: 34  |  |  - Meeting Notes (edited yesterday) | |
|  |                  |  |  - Product Spec (edited 3 days ago)  | |
|  +------------------+  +--------------------------------------+ |
|                                                                  |
+================================================================+

Dashboards are your home screen. Widgets are the cards on it.

You can have multiple dashboards (just like multiple home screen pages on your phone). Each dashboard contains widgets arranged in a grid that you can resize and rearrange.

Widget types include:

• Number widget -- shows a single big number (e.g., "12 tasks remaining")
• Chart widget -- bar chart, line chart, pie chart of your data
• Table widget -- a compact table showing a few rows
• Calendar widget -- a small monthly calendar
• Task List widget -- a checklist of items
• Custom widget -- write your own code (React component in a sandbox)

Key points:

• Small card on a Dashboard page
• Shows a compact summary or visualization
• Quick glance -- no need to open the full Module
• Dashboards can contain many widgets arranged in a grid
• Two types: Preset (built-in) and Custom (user code)

How Data Flows Between Layers

Let us walk through a concrete example from start to finish. Imagine you are setting up task management in GOD CRM.

Step 1: Layer 1 is born

You create a new table called "Tasks" with columns: title, status, assignee, due_date, priority. The system creates rows in universal_tables and you start adding data to table_rows.

Layer 1:  [Tasks table created in database]

Step 2: Layer 2 -- you browse your data

You click "Tasks" in the sidebar under Tables. A grid appears showing all your tasks in rows and columns. This is Layer 2 -- the data browser.

Layer 2:  Grid view of Tasks table
Layer 1:  [Tasks table in database]

Step 3: Still Layer 2 -- you filter and sort

You apply a filter to show only tasks where priority = "High". You sort by due_date. The grid updates instantly. This is still Layer 2 -- same table, just filtered and sorted.

Layer 2:  Grid view of Tasks table  (filtered: priority = High)
Layer 1:  [Tasks table in database]

Step 4: Layer 3 -- you open a Module

You open the Kanban Module from the sidebar. Now your tasks appear as cards grouped by status: To Do, In Progress, Done. You drag a card from "To Do" to "In Progress" and the underlying data updates. This is Layer 3 -- a full-page app with its own UI, drag-and-drop, swimlanes, and a detail panel.

Layer 3:  Kanban Module (full-page app with drag-and-drop)
Layer 2:  Grid view (spreadsheet-like table)
Layer 1:  [Tasks table in database]

Step 5: Layer 4 -- you add a dashboard widget

You go to your Dashboard and add a "Number" widget configured to show the count of tasks where status = "To Do". It displays: "12 tasks remaining". You also add a Chart widget showing tasks completed per week.

Layer 4:  [12 tasks remaining]  [Tasks/week chart]   <-- Dashboard
Layer 3:  Kanban Module, Calendar Module             <-- Sidebar
Layer 2:  Grid view (table with filters and sorting) <-- Tables
Layer 1:  [Tasks table in database]                  <-- Hidden

All four layers are now active, all reading from the same data.

The Key Insight

Here is the most important thing to understand:

The SAME data (Layer 1) can appear in ALL other layers simultaneously.

+------------------------------------------------------------------+
|                                                                    |
|   ONE table in Layer 1 can power:                                 |
|                                                                    |
|   - A Grid view with filters and sorting (Layer 2)                |
|   - A Kanban Module with drag-and-drop cards (Layer 3)            |
|   - A Calendar Module with day/week/month views (Layer 3)         |
|   - A Documents Module with rich text editing (Layer 3)           |
|   - A Number widget on Dashboard (Layer 4)                        |
|   - A Chart widget on Dashboard (Layer 4)                         |
|                                                                    |
|   ALL AT THE SAME TIME.                                           |
|                                                                    |
|   Change the data in ONE place --> it updates EVERYWHERE.         |
|                                                                    |
+------------------------------------------------------------------+

If you edit a task's status in the Grid view (Layer 2), the Kanban Module (Layer 3) instantly shows the card in a different column, and the Dashboard widget (Layer 4) updates its count.

There is no syncing, no copying, no "refresh to see changes." Every layer reads from the same source of truth: Layer 1.

Module vs Widget -- The Most Common Confusion

This is where most people get confused, so let us be very clear.

+-----------------------------+-------------------------------+
|         MODULE              |          WIDGET               |
|        (Layer 3)            |         (Layer 4)             |
+-----------------------------+-------------------------------+
| Full-page application       | Small card                    |
| Lives in the sidebar        | Lives on a Dashboard          |
| Has its own UI and logic    | Shows a summary or chart      |
| You interact with it deeply | You glance at it quickly      |
| Example: Calendar app       | Example: Mini calendar card   |
| Example: Documents editor   | Example: Recent docs list     |
| Example: AI Agents config   | Example: Agent status counter |
+-----------------------------+-------------------------------+

The Android analogy makes this crystal clear:

• A Module is like the Google Calendar app. You open it, you see your full schedule, you create events, you set reminders, you switch between day/week/month views. It is a complete experience.

• A Widget is like the Calendar home screen widget. It shows you today's next 3 events in a small card. You do not create events from it. You glance at it and move on.

Same data. Very different experience. Very different purpose.

When to use what:

• Need to work with your data? Open the Module (Layer 3).
• Need to check on your data? Look at the Widget (Layer 4).

Why Four Layers?

You might wonder: why not just two layers (storage + UI)? Why exactly four?

1. Flexibility -- same data, many presentations

Without layers, you would need separate databases for your table, your kanban module, your calendar module, and your dashboard. With four layers, one table powers all of them.

2. Separation -- storage is independent from presentation

Your data does not care how it is displayed. Contacts are contacts whether you see them in a grid, a kanban board, or a chart. Separating storage (Layer 1) from presentation (Layers 2-4) means you can change the UI without touching the data.

3. Power -- build custom apps on top of raw data

Modules (Layer 3) let you build full applications -- with custom logic, custom layouts, custom interactions -- all on top of the same universal table system. The Documents module, the Labs mind-mapping tool, and the Wellness tracker all use different UIs but the same underlying storage.

4. Simplicity -- widgets give you a quick overview

Widgets (Layer 4) solve the "I just want to glance at my data" problem. You do not need to open a full Module to see how many tasks are overdue. A small dashboard card tells you in half a second.

5. Consistency -- the universal table is the common language

Because everything goes through Layer 1, all your data is in one format. You can link tables to each other, create cross-table formulas, and build widgets that combine data from multiple tables. There are no data silos.

Summary Table

Remember the direction:

Layer 1   -->   Layer 2   -->   Layer 3   -->   Layer 4
Storage         Browsing        Full App        Quick Glance
(hidden)        (table views)   (sidebar)       (dashboard)

Each layer adds more specialization and less raw data. Layer 1 has everything. Layer 4 shows just the highlights.

Sidebar Structure and the Four Layers

Here is how the four layers map to what you actually see in the GOD CRM sidebar:

Space: "My Business"
  |
  +-- Project: "Client Management"
  |     |
  |     +-- Dashboards            <-- Layer 4 (contains Widgets)
  |     |     +-- Main Dashboard
  |     |     +-- Sales Overview
  |     |
  |     +-- Tables                <-- Layer 2 (grid view of your data)
  |     |     +-- Contacts
  |     |     +-- Deals
  |     |     +-- Invoices
  |     |
  |     +-- Modules               <-- Layer 3 (full-page apps)
  |           +-- Kanban Board
  |           +-- Calendar
  |           +-- Timeline
  |           +-- Documents
  |
  +-- Project: "Internal Tools"
        +-- Dashboards
        +-- Tables
        +-- Modules

Layer 1 (Raw Tables) is not visible in the sidebar. It is underneath everything, in the database.

Quick Reference: "Where Does X Live?"

What Is Next?

Now that you understand the four layers, the next question is: how are tables, modules, and dashboards organized? They live inside Spaces and Projects -- the organizational structure of GOD CRM.

Continue to 03-spaces-and-projects.md to learn how Spaces and Projects work.