Chapter 3: Designing Your Own Domain

"You already know your domain better than anyone. This chapter teaches you to see it the way Data Publisher does — as entities, relationships, and documents waiting to be automated."

The Moment of Recognition

There is a specific moment that happens when someone who has studied SchoolCoop deeply turns their attention to their own industry. It usually comes quietly, somewhere between the enrollment table and the foreign key map. They stop reading about homeschool co-ops and start seeing something else entirely.

A paralegal sees clients, matters, hearings, attorneys, documents. A property manager sees landlords, tenants, units, leases, maintenance requests, documents. A nonprofit coordinator sees donors, campaigns, volunteers, events, grants, documents. The entities are different. The relationships are different. The documents are completely different.

The pattern is identical.

That is the moment this chapter is designed to create for you, if you have not already had it. Everything SchoolCoop demonstrates — the organizational anchor, the temporal structure, the junction tables, the financial layer, the safety data, the 20 document types organized by stakeholder and operational phase — all of it applies to your domain. The names change. The architecture does not.

This chapter walks you through the process of designing a domain from scratch. We will use a hypothetical legal services domain as our working example, building it step by step alongside the instructions so you can see both the process and a concrete application simultaneously. By the end of this chapter, you will have a complete domain design document for your own industry — ready to build in Chapters 4 and 5.

Before You Open a Text Editor

The single most common mistake new domain builders make is starting with the technology. They open a CSV file and start typing column names. They copy domain-config.json and start editing. They look at the generator script and start modifying it for their industry.

This is backwards. And it is expensive. Every hour you spend building a domain whose architecture is wrong is an hour you will spend rebuilding it later.

Design on paper first. Or a whiteboard. Or a napkin. The medium does not matter. What matters is that you think through the architecture completely before you write a single line of code or a single row of data. The design phase costs you two to four hours. Getting the design wrong and rebuilding costs you two to four days.

The design phase has three distinct steps: identifying your entities, mapping your documents, and validating the connection between the two. We will go through each one.

Step One: Identify Your Entities

An entity is a real-world thing your organization tracks. Not a data field. Not a document. A thing — something that has its own identity, its own attributes, and relationships to other things.

The fastest way to identify your entities is to answer four questions about the organization your domain will serve.

Question 1: Who does the organization serve?

Write down every type of person who interacts with the organization. Not just customers — everyone. Staff, clients, vendors, partners, beneficiaries, volunteers. Each distinct role is a candidate entity.

For a legal services firm: clients, attorneys, paralegals, opposing counsel, witnesses, experts, judges.

Not all of these will become tables. Opposing counsel and judges, for example, may only appear as text fields in document templates rather than as full entities with their own records. The goal of this question is to surface all the people before you decide which ones need their own table.

Question 2: What does the organization produce or provide?

Write down the core offerings — the things the organization exists to deliver. Services, products, cases, projects, properties, courses, treatments. These are almost always primary entities.

For a legal services firm: matters (cases). A matter is what a law firm produces. Everything else — the attorneys, the hearings, the documents, the billing — exists in relationship to a matter.

Question 3: What events or activities does the organization manage?

Write down the things that happen over time — the scheduled events, the milestones, the transactions, the interactions. These often become either their own tables or junction tables connecting the people to the offerings.

For a legal services firm: hearings, depositions, deadlines, billing entries, communications, documents filed.

Question 4: What does the organization track for compliance, safety, or financial purposes?

Write down the data the organization must maintain regardless of whether it seems interesting. Contracts, payments, certifications, licenses, insurance records, consent forms.

For a legal services firm: retainer agreements, invoices, payments, conflict checks, bar admissions, malpractice insurance.

From Questions to Entities: The Legal Services Example

Running a mid-size general practice law firm through these four questions produces this initial entity list:

Who: Clients, Attorneys, Paralegals, Expert witnesses What: Matters (cases) Events: Hearings, Deadlines, Billing entries, Communications Compliance: Retainer agreements, Invoices, Payments

Now apply the first filter: which of these need their own table versus being fields in another table?

Expert witnesses are referenced occasionally in documents but do not need a full entity record in the MVP — a text field in the matter record is sufficient. Paralegals can be folded into a staff table with attorneys. Communications are important but their structure varies so much that a simple notes field per matter may be sufficient for document generation purposes.

After filtering, the core entities for a legal services domain are:

firms — the organizational anchor (the law firm itself)
practice_areas — the temporal/categorical structure (analogous to academic terms)
clients — the billing unit (analogous to families)
matters — the core offering (analogous to classes)
attorneys — the staff (analogous to teachers)
client_matters — the junction table (analogous to enrollments)
hearings — the scheduled events (analogous to field trips)
deadlines — the time-critical operational data
billing_entries — the financial detail (analogous to fees)
invoices — the billing records (analogous to payments)
documents_filed — the compliance record

Eleven tables. Compared to SchoolCoop's fifteen, this feels leaner — and it is. A legal domain can be built correctly with eleven tables. A co-op domain needed fifteen because the safety data (emergency contacts, medical information, allergies) added three tables that a legal domain does not require.

This is the important lesson: the right number of tables is the number that correctly models your domain. Not more, not fewer. SchoolCoop has fifteen because a co-op needs fifteen. Your domain has whatever number it needs.

Step Two: Map Your 20 Document Types

With your entities identified, turn to the documents. Your domain needs exactly 20 document templates. This section explains how to find them.

The same six categories that organize SchoolCoop's templates organize every domain:

Category 1: Operational Documents (Daily/Weekly Use) These are the documents generated most frequently — the working documents of the organization's day-to-day operation. Aim for 4–5 templates here.

For legal services: Matter Status Report, Active Case List, Attorney Workload Summary, Deadline Calendar, Client Contact Sheet.

Category 2: Client/Customer Communications (Regular Touchpoints) Documents that go directly to the people the organization serves. Professional, branded, accurate. Aim for 4–5 templates here.

For legal services: Engagement Letter, Client Status Update, Case Summary Letter, Invoice, Payment Receipt.

Category 3: Legal/Compliance Documents (Critical) Documents required by law, regulation, or professional obligation. These need to be exactly right. Aim for 3–4 templates here.

For legal services: Retainer Agreement, Conflict of Interest Disclosure, Attorney-Client Privilege Notice, File Closing Letter.

Category 4: Court and Proceeding Documents (Event-Driven) Documents generated in response to scheduled events. Aim for 3–4 templates here.

For legal services: Hearing Preparation Sheet, Deposition Outline, Expert Witness Summary, Court Appearance Checklist.

Category 5: Marketing and Business Development (Periodic) Documents that help the firm grow and communicate its capabilities. Aim for 2–3 templates here.

For legal services: Case Results Summary, Attorney Biography Sheet, Practice Area Overview.

Category 6: Administrative and Financial (Management) Documents for internal management rather than external distribution. Aim for 2–3 templates here.

For legal services: Monthly Billing Summary, Matter Profitability Report.

Count those up: 5 + 5 + 4 + 4 + 3 + 2 = 23. Trim the least essential three — perhaps the Expert Witness Summary (edge case), the Practice Area Overview (static content), and the Matter Profitability Report (too complex for MVP) — and you have your 20.

The 20-Template Discipline

When you first list your document types, you will probably generate more than 20. This is good — it means you are thinking comprehensively. The discipline of trimming to exactly 20 forces important decisions.

When choosing which templates to include and which to defer, apply these filters:

Frequency filter: How often is this document generated? A template generated monthly serves users better than one generated once a year. Prefer frequency.

Stakeholder filter: Whose needs does this document serve? A domain that has 15 templates serving administrators and 5 serving clients is unbalanced. Prefer balance across stakeholders.

Complexity filter: Is this template's data available in your current table structure? A template that requires data you have not modeled yet should be deferred until your schema supports it.

Distinctiveness filter: Does this template serve a genuinely different purpose from others, or is it a variation on an existing template? If a Client Status Update and a Case Summary Letter are essentially the same document with different headings, they should be one template, not two.

Apply all four filters to your initial list. The 20 that survive are your domain's MVP template set.

Step Three: Validate the Connection

You now have a list of entities and a list of 20 document templates. Before you go any further, you need to validate that every template is fully supported by your entity structure.

For each of your 20 templates, trace the data path:

What is the primary table this template generates from?
What related tables does it need to pull data from?
Is the relationship between those tables defined by a foreign key in your entity map?

If the answer to question 3 is no — if a template needs data from two tables that have no defined relationship — you have found a gap in your schema. Fix it before you build.

Let us trace three legal services templates to demonstrate:

Engagement Letter Primary table: matters Related tables: clients (for client name and address), attorneys (for responsible attorney), firms (for firm letterhead) Relationships: matters.ClientID → clients.ClientID ✓, matters.AttorneyID → attorneys.AttorneyID ✓, matters.FirmID → firms.FirmID ✓ Result: All relationships defined. Template is fully supported.

Invoice Primary table: invoices Related tables: clients (for billing address), matters (for matter description), billing_entries (for line items) Relationships: invoices.ClientID → clients.ClientID ✓, invoices.MatterID → matters.MatterID ✓, billing_entries.InvoiceID → invoices.InvoiceID ✓ Result: All relationships defined. Template is fully supported.

Hearing Preparation Sheet Primary table: hearings Related tables: matters (for case details), clients (for client information), attorneys (for lead attorney), deadlines (for related deadlines) Relationships: hearings.MatterID → matters.MatterID ✓, then matters.ClientID → clients.ClientID ✓, hearings.AttorneyID → attorneys.AttorneyID ✓, deadlines.MatterID → matters.MatterID ✓ Result: All relationships defined, but the client information requires a two-hop join (hearings → matters → clients). This is supported by Data Publisher's master-detail relationship system. Template is fully supported.

Run this validation for all 20 templates. Any template that fails — that requires data from an unconnected table — either needs a new foreign key relationship added to your schema, or needs to be redesigned to use data that is already connected.

This validation step is where most schema gaps surface. It is far better to find them now than after you have written 300 rows of sample data.

Step Four: Name Your Tables and Define Your Foreign Keys

With validation complete, formalize your schema. For each table, define:

Table name (lowercase, underscored, plural: clients, billing_entries, client_matters)
Primary key (conventionally TableID in singular form: ClientID, MatterID)
Foreign keys (every relationship to another table, explicitly named)
Core fields (the columns you know you will need — not exhaustive, but enough to define the shape)

Here is the formal schema definition for the legal services domain:

firms
  FirmID (PK)
  FirmName, Address, City, State, ZipCode
  Phone, Email, Website
  ManagingPartner, Founded
  BarNumber, MalpracticeInsurer

practice_areas
  PracticeAreaID (PK)
  FirmID (FK → firms.FirmID)
  AreaName, Description, Status

clients
  ClientID (PK)
  FirmID (FK → firms.FirmID)
  ClientType (Individual/Entity)
  FirstName, LastName, CompanyName
  Address, City, State, ZipCode
  Phone, Email
  DateOnboarded, Status, ReferralSource

matters
  MatterID (PK)
  FirmID (FK → firms.FirmID)
  ClientID (FK → clients.ClientID)
  LeadAttorneyID (FK → attorneys.AttorneyID)
  PracticeAreaID (FK → practice_areas.PracticeAreaID)
  MatterNumber, Description, Status
  OpenDate, CloseDate, EstimatedValue
  BillingType, HourlyRate, FlatFee, RetainerAmount

attorneys
  AttorneyID (PK)
  FirmID (FK → firms.FirmID)
  FirstName, LastName, Title
  BarNumber, BarAdmissionDate, BarState
  Email, Phone, Specialty
  HourlyRate, Status

hearings
  HearingID (PK)
  MatterID (FK → matters.MatterID)
  AttorneyID (FK → attorneys.AttorneyID)
  HearingType, CourtName, JudgeName
  ScheduledDate, ScheduledTime, Location
  Status, Outcome, Notes

deadlines
  DeadlineID (PK)
  MatterID (FK → matters.MatterID)
  AttorneyID (FK → attorneys.AttorneyID)
  DeadlineType, Description
  DueDate, Status, Priority, Notes

billing_entries
  EntryID (PK)
  MatterID (FK → matters.MatterID)
  AttorneyID (FK → attorneys.AttorneyID)
  InvoiceID (FK → invoices.InvoiceID, nullable)
  EntryDate, Description
  Hours, HourlyRate, Amount
  BillingStatus

invoices
  InvoiceID (PK)
  ClientID (FK → clients.ClientID)
  MatterID (FK → matters.MatterID)
  InvoiceNumber, InvoiceDate, DueDate
  TotalHours, TotalAmount, AmountPaid, Balance
  Status, Notes

documents_filed
  DocumentID (PK)
  MatterID (FK → matters.MatterID)
  AttorneyID (FK → attorneys.AttorneyID)
  DocumentType, Title, FiledDate
  Court, CaseNumber, Status, StorageLocation

Ten tables. Lean, complete, and fully connected. Every foreign key relationship is defined. Every template validation from Step Three passes against this schema.

The Design Document

Before you move to building, consolidate everything into a single design document. This is your blueprint — the reference you will consult throughout the build phase, and the document you will share with collaborators if you are not building alone.

A domain design document has five sections:

Section 1: Domain Overview Name, target organization type, target user, the problem it solves, and the primary value proposition. Two to three paragraphs. This is also your eventual marketplace description.

Section 2: Entity Map A visual or textual representation of all your tables and their relationships — similar to the diagram in Chapter 2 showing SchoolCoop's foreign key web. Draw it by hand if you need to. What matters is that you can see the whole architecture at once.

Section 3: Table Definitions For each table: name, primary key, foreign keys, and core fields. The schema definition above is exactly the right format.

Section 4: The 20 Document Templates Organized by the six categories. For each template: name, description, primary table, related tables, complexity level (Simple / Moderate / Complex), and intended user (administrator, attorney, client, etc.).

Section 5: Sample Data Plan How many records will you create for each table? What scenarios will your sample data cover? What edge cases must be represented? Write this out before you create a single CSV row.

A good design document is 10 to 15 pages. It takes two to four hours to produce. And it is the single best investment you can make before the build phase begins.

Designing for the Wow Moment

There is a specific experience you are designing for — the moment when someone downloads your domain, loads it into Data Publisher, selects a template, and clicks Run for the first time. What they see in that moment determines whether they become a paying subscriber or close the window.

That moment is determined entirely by your sample data and your template design. The architecture is invisible to them. The foreign keys are invisible. The domain-config.json is invisible. What they see is a document.

Make that document extraordinary.

For the legal services domain, the first document a new user should generate is the Engagement Letter. It should look exactly like an engagement letter from a real law firm — the firm's name and address in the header, the client's name and address in the proper position, the matter description specific and professional, the attorney's name and bar number at the signature, the fee arrangement clearly stated. It should look like something a first-year associate would be proud to send out.

If instead the engagement letter shows "Law Firm 1" in the header, "Client A" as the recipient, and "Matter Description Here" as the matter description — it looks like a template. It does not produce the wow moment. It produces a shrug.

The wow moment requires two things working together: realistic sample data that feels like it came from a real organization, and template design that produces a document you would actually want to send. Neither works without the other.

Chapter 4 covers sample data creation in complete detail, with specific guidance on building the kind of data that produces that moment. But hold the goal in mind as you complete your design: someone's first generated document should make them think, "I can use this today."

Common Design Mistakes and How to Avoid Them

Mistake 1: Too few tables, too much data per table

The temptation is to simplify — put the client's address in the matters table, put the attorney's bar number in the billing entries table, avoid the "complexity" of foreign keys. This produces tables with 40 columns that are difficult to maintain and impossible to template correctly.

The fix: if a piece of data belongs to an entity (client address belongs to the client, bar number belongs to the attorney), put it in that entity's table. Use foreign keys to connect the tables. This is not complexity — it is correctness.

Mistake 2: Missing the junction table

Many-to-many relationships are everywhere in real domains, and they are consistently underidentified by new domain designers. An attorney can work on many matters; a matter can have many attorneys. A client can have many matters; a matter belongs to one client (usually). A template can draw from many tables; a table can feed many templates.

The fix: whenever you see a many-to-many relationship — whenever you would need to store a comma-separated list of IDs in a single field — create a junction table. Junction tables are almost always where the richest per-relationship data lives.

Mistake 3: Template sprawl

It is tempting to design 30 templates "just in case." Resist this. A domain with 30 templates that are 70% built is worse than a domain with 20 templates that are 100% built. Completeness and quality beat breadth.

The fix: design 20 templates, build all 20 completely, validate all 20 against real sample data. If you find important templates missing after launch, add them in version 1.1 when you have user feedback to guide you.

Mistake 4: Sample data that tells the wrong story

A domain for a healthcare practice that has sample patients named "Patient One," "Patient Two," and "Patient Three" does not demonstrate that the domain is real and useful. It demonstrates that the domain was built by someone who did not think about the user's experience.

The fix: spend real time on your sample data names, scenarios, and details. They are not throw-away test data — they are the primary sales tool your domain has.

Mistake 5: Designing for your own use case, not for a category

If you are a legal services consultant building a domain for your own firm, you will be tempted to model your firm's specific workflow — your billing codes, your case numbering system, your document naming conventions. The domain you publish to the marketplace must serve hundreds of firms, not just yours.

The fix: after completing your initial design, ask: "Would a law firm in a different city, with different practice areas, using different billing software, find this domain useful?" If the answer depends on details specific to your firm, generalize those details.

Your Design Work: A Guided Exercise

Stop reading and do this now. The domain you design in the next two to four hours is the domain you will build in Chapters 4 and 5.

Step 1 (30 minutes): Answer the four entity questions for your chosen domain. Write down every entity candidate without filtering. Be generous. You can trim later.

Step 2 (30 minutes): Apply the filtering criteria. Which entities need their own table? Which can be fields in another table? Which are out of scope for an MVP?

Step 3 (45 minutes): List your document types by category. Start with all the documents you can think of, then trim to the best 20 using the four filters.

Step 4 (45 minutes): Validate every template against your entity map. Find and fix every schema gap.

Step 5 (30–60 minutes): Write your design document. All five sections. This is your blueprint.

When you have a complete design document for your domain, you are ready for Chapter 4.

A Note on Domain Expertise

Throughout this chapter, we have assumed that you are the domain expert — that you are a paralegal building a legal services domain, a property manager building a property management domain, a nonprofit coordinator building a volunteer management domain.

If you are a developer building a domain for an industry you do not know deeply, the design process is the same, but step zero is different: talk to someone who works in that industry before you begin. Spend two hours with a practicing attorney before designing a legal services domain. Talk to an actual property manager before designing a property management domain.

The technical architecture of any domain takes 15 hours to build. The domain knowledge that makes the architecture correct takes years to accumulate. If you do not have that knowledge, borrow it. The people who work in your target industry will be glad to help — especially when you tell them what you are building for them.

The trilogy — particularly Volume 3, which covers how human knowledge becomes machine-readable data — goes deep into this process of knowledge capture from domain experts. If you find yourself designing a domain for an unfamiliar industry, Volume 3 is your guide to asking the right questions.

Chapter Summary

Domain design begins with four questions about the organization: who does it serve, what does it provide, what events does it manage, and what does it track for compliance. The answers produce your initial entity list, which you filter into a clean table schema.

Twenty document templates organized across six categories — operational, communications, compliance/safety, event-driven, marketing, and administrative — provide systematic coverage of every stakeholder and every operational phase.

Validation connects the two: every template must be traceable through your foreign key structure to every piece of data it requires. Gaps found in validation are far cheaper to fix than gaps found in testing.

The design document — five sections, 10 to 15 pages, two to four hours to produce — is your blueprint for the build phase. Do not skip it.

The wow moment — the experience of a new user generating their first document — is determined by your sample data and your template quality. Design for that moment from the beginning.

What's Next

Chapter 4 covers the build phase: creating your CSV sample data, writing your domain-config.json, and planning your template structure. The design work is done. Now we make it real.

Volume 5 — Building Intelligent Systems: Building Organizational Knowledge Systems on Data Publisher for Word Part of the Building Intelligent Systems Series