---
title: "Core Concepts"
description: "Understanding the fundamental building blocks of the application"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.testandaccept.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

Welcome to the core concepts guide. This section explains the fundamental building blocks of the application and how they work together to help you manage client work, track deliverables, and collaborate with your team.

## Overview

The application is built around a hierarchical structure that mirrors how professional services work is organized in the real world:

<pre class="mermaid">{`
flowchart TB
  User[Users] -->|belong to| Org[Organizations]
  User -->|have access to| Project[Projects]
  Org -->|own| Client[Clients]
  Org -->|manage| Project
  Client -->|engage in| Project
  Project -->|deliver| SOW[Statements of Work]
  Project -->|propose changes via| RFC[RFCs]
  RFC -->|optionally link to| SOW
  SOW -->|contain| Item[Work Items]
  Item -->|must meet| Criterion[Acceptance Criteria]
  Criterion -->|verified by| Test[Tests]

  style User fill:#e8e8ff
  style Org fill:#e1f5ff
  style Client fill:#fff9c4
  style Project fill:#fff4e6
  style SOW fill:#e8f5e9
  style RFC fill:#ffe6f0
  style Item fill:#f3e5f5
  style Criterion fill:#ffe6e6
  style Test fill:#e6f7ff
`}</pre>

## The Building Blocks

### Users

**People and Accounts**

Users are the people who work in the application - you, your teammates, clients, and collaborators. Each user has an individual account with different access levels to various resources.

**What you can do**:
- Manage your account and profile
- Belong to multiple organizations
- Have different access levels to resources
- Collaborate with teammates and clients
- Create API tokens for automation

[Learn more about Users →](/concepts/users/)

### Organizations

**Your Workspace**

Organizations are the top-level container for your team. Think of an organization as your company's dedicated workspace where you and your colleagues collaborate on client work.

**What you can do**:
- Create a workspace for your team
- Invite colleagues to collaborate
- Manage access and permissions
- Switch between multiple organizations if you belong to more than one

[Learn more about Organizations →](/concepts/organizations/)

### Clients

**The Companies You Work With**

Clients represent the organizations or companies that engage your services. Each client record stores contact information, relationship details, and links to all the work you do for them.

**What you can do**:
- Track your business relationships
- Store multiple contacts per client
- Link projects to specific clients
- View your complete history with each client

[Learn more about Clients →](/concepts/clients/)

### Projects

**Organizing Client Work**

Projects are containers for related work with a specific client. They represent an engagement, initiative, or body of work that may include multiple deliverables.

**What you can do**:
- Group related work together
- Connect deliverables to clients
- Track project status and timeline
- Manage team access and collaboration

[Learn more about Projects →](/concepts/projects/)

### Statements of Work (SOWs)

**Defining What You'll Deliver**

A Statement of Work is a detailed document that outlines exactly what will be delivered for a project. It's like a contract that specifies what you'll build, how it will be tested, and who needs to approve it.

**What you can do**:
- Define deliverables and scope
- Break down complex projects
- Get client approval on deliverables
- Track version history as requirements change

[Learn more about Statements of Work →](/concepts/statements-of-work/)

### Work Items

**Breaking Down the Work**

Items are the individual pieces of work within a Statement of Work. They come in five types:

- **Requirements**: What needs to be built
- **Tasks**: Specific work to be done
- **Milestones**: Important dates and checkpoints
- **Dependencies**: External blockers
- **Deliverables**: Client-facing outputs

**What you can do**:
- Organize work into manageable pieces
- Create hierarchical work structures
- Track different types of work appropriately
- See clear breakdown of what needs to be done

[Learn more about Work Items →](/concepts/task-items/)

### Acceptance Criteria

**Defining "Done"**

Acceptance Criteria are the specific conditions that must be met for work to be considered complete. They answer the question: "How will we know when this is done?"

**What you can do**:
- Set clear expectations
- Align team and client understanding
- Create testable conditions
- Prevent scope creep

[Learn more about Acceptance Criteria →](/concepts/criterion/)

### Tests

**Verifying Quality**

Tests are the specific procedures you perform to verify that acceptance criteria have been met. They're the practical steps that confirm what you built actually works as intended.

**What you can do**:
- Verify work meets requirements
- Catch problems early
- Document expected behavior
- Track which tests are passing

[Learn more about Tests →](/concepts/tests/)

### Requests for Change (RFCs)

**Documenting Technical Decisions**

RFCs (Requests for Change) are structured documents used to propose, discuss, and document significant technical or organizational decisions before implementing them.

**What you can do**:
- Propose significant changes
- Document decision-making process
- Get team feedback before committing
- Create historical record of why decisions were made
- Identify risks and alternatives early

[Learn more about RFCs →](/concepts/rfcs/)

### Root Cause Analyses (RCAs)

**Learning From What Went Wrong**

A root cause analysis records why an incident, defect or failed acceptance happened, the evidence for the cause, and the solutions chosen, and links it to the SOW versions involved.

**What you can do**:
- Capture the timeline and severity of a problem
- Agree the underlying cause, with reasoning
- Plan corrective and preventive actions
- Link the issue to the SOW version that introduced or fixed it

[Learn more about Root Cause Analyses →](/concepts/root-cause-analyses/)

## How They Work Together

### The Workflow

Here's how these concepts work together in a typical workflow:

1. **Create Your Account**
   - Sign up as a new user
   - Set up your profile
   - Enable security features (2FA)

2. **Setup Your Organization**
   - Create or join an organization
   - Invite your team members
   - Configure settings and preferences

3. **Add Your Client**
   - Create a client record
   - Add contact information
   - Document the relationship

4. **Create a Project**
   - Link to the client
   - Set project timeline
   - Add team members as followers

5. **Define Your Deliverables**
   - Create Statements of Work
   - Break down into work items
   - Define acceptance criteria
   - Write tests to verify quality

6. **Execute and Track**
   - Complete work items
   - Run tests to verify
   - Track progress
   - Get client approval

7. **Close and Archive**
   - Complete final deliverables
   - Get sign-off
   - Archive completed work

## Understanding the Hierarchy

### Required Relationships

Some relationships are required:

- **Clients must belong to an Organization**
  - Ensures proper data isolation
  - All organization members can access

- **Work Items must belong to a Statement of Work**
  - Keeps work organized
  - Links tasks to deliverables

- **Acceptance Criteria must belong to a Work Item**
  - Defines what "done" means
  - Provides testing targets

- **Tests must verify an Acceptance Criterion**
  - Links verification to requirements
  - Ensures quality checks

### Optional Relationships

Other relationships are optional but recommended:

- **Projects can belong to an Organization**
  - Recommended for team collaboration
  - Can be personal if needed

- **Statements of Work can belong to an Organization**
  - Recommended for visibility
  - Can be personal for individual work

- **Projects can link to Clients**
  - Recommended for tracking relationships
  - Helps organize by customer

## Access and Permissions

### User Access Model

The application uses a flexible access model:

**Users** → belong to → **Organizations** → own → **Resources**

Additionally, users can be granted direct access to specific resources without joining the organization.

### Organization-Level Access

When you're a member of an organization:
- You automatically see all clients in that organization
- You can access projects assigned to the organization
- You can collaborate on organization SOWs
- Your access level depends on your organization role

### Resource-Level Access

For finer control:
- Grant specific access to individual projects
- Invite external collaborators with limited permissions
- Set time-limited access for contractors or partners
- Different users can have different access levels to the same resource

### Five Access Levels

**Owner**: Full control including deletion and access management

**Editor**: Can view and modify resources

**Approver**: Can review and approve, but not edit

**Viewer**: Read-only access to see resources

**Follower**: Receive updates and notifications only

[Learn more about Users and Access →](/concepts/users/)

## Progress Tracking

### How Completion is Calculated

The application tracks progress at multiple levels:

**Statement of Work Progress** (Weighted):
- 40% from completed work items
- 30% from met acceptance criteria
- 30% from passing tests

This gives you an overall completion percentage (0-100%) that considers not just what's done, but also whether it meets requirements and passes quality checks.

### Why This Matters

This three-part calculation ensures:
- You can't mark work complete without meeting criteria
- Quality is verified through testing
- Progress reflects real completion, not just tasks checked off

## Best Practices

### Starting Out

**For New Users**:
1. Sign up and create your account
2. Set up your profile and security (enable 2FA)
3. Create or join an organization
4. Add your first client
5. Create a project for that client
6. Build your first Statement of Work

**For Teams**:
1. Admin creates organization
2. Admin invites team members
3. Team members set up their accounts
4. Establish naming conventions
5. Define your workflow

### Organizing Your Work

**Keep It Simple**:
- Don't over-nest work items (2-3 levels max)
- Use clear, descriptive names
- Update status as work progresses
- Archive completed work to keep lists clean

**Use the Right Tool**:
- Use Requirements for high-level features
- Use Tasks for specific implementation work
- Use Milestones for important dates
- Use Dependencies for external blockers
- Use Deliverables for client-facing outputs

### Collaboration Tips

**Communication**:
- Link projects to organizations for team visibility
- Use followers to keep stakeholders informed
- Update descriptions with important context
- Keep contact information current

**Quality**:
- Write testable acceptance criteria
- Create tests at the same time as criteria
- Run tests regularly
- Don't ignore failing tests

## Common Patterns

### Feature Development

When building a new feature:

1. Create a **Requirement** for the feature
2. Break down into **Tasks** for implementation
3. Add **Acceptance Criteria** for each task
4. Write **Tests** to verify criteria
5. Mark a **Milestone** for completion
6. Create a **Deliverable** for what ships

### Client Project

When starting work with a client:

1. Create or update the **Client** record
2. Add **Contacts** for key people
3. Create a **Project** linked to the client
4. Build **Statements of Work** for deliverables
5. Break SOWs into **Work Items**
6. Define **Criteria** and **Tests**
7. Execute work and track progress

### Multi-Phase Engagement

For long-term client work:

1. Create one **Project** for the overall engagement
2. Create separate **SOWs** for each phase
3. Use **Milestones** to mark phase completion
4. **Archive** completed SOWs as you go
5. Keep the Project active across phases

### Technical Decision Making

When proposing significant changes:

1. Create an **RFC** within the relevant **Project**
2. Document the problem, solution, and alternatives
3. Invite **Collaborators** to review and provide feedback
4. Refine the RFC based on discussion
5. Make a decision (accept, reject, or defer)
6. Close the RFC and document the rationale
7. If accepted, create **Work Items** to implement
8. Link implementation tasks back to the RFC

## Getting Help

### Finding Information

Each concept page includes:
- Detailed explanations of properties
- Common workflows and patterns
- Best practices and tips
- Troubleshooting guidance
- Links to related concepts

### Navigation

Use the sidebar to jump between concept pages, or follow the links in the "Related Concepts" section at the bottom of each page.

## Explore the Concepts

- **Users**
- **Organizations**
- **Clients**
- **Projects**
- **Statements of Work**
- **Work Items**
- **Acceptance Criteria**
- **Tests**
- **RFCs**
- **Root Cause Analyses**

Source: https://docs.testandaccept.com/concepts/index.mdx