# actigraph/centrepoint3apidocumentation architecture

> Architecture diagram of the GitHub repository actigraph/centrepoint3apidocumentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/actigraph/centrepoint3apidocumentation
- Repository: https://github.com/actigraph/centrepoint3apidocumentation

## Overview

This repository is not application code; it is the Markdown documentation for the CentrePoint V3 API. Architecturally, it describes a public integration surface between external client systems and ActiGraph’s CentrePoint study-admin platform.

1. **Top-level system boundary**
   The API exposes CentrePoint study administration and de-identified subject data through two hosted endpoints: the API at `api.actigraphcorp.com` and OAuth authorization at `auth.actigraphcorp.com`. The documentation positions CentrePoint as the internal system of record and the API as its external integration layer.

2. **Access and security layer**
   All interaction is authenticated through OAuth 2.0, and the API requires HTTPS. Requests and responses are JSON-based. This means any architecture diagram should show a distinct auth service in front of the API, with client applications obtaining tokens before calling resource endpoints.

3. **Core study management domain**
   The main CRUD-style domain is study administration: studies, sites, subjects, activity monitors, assignments, study milestones, uploads, and visit files. These resources form the operational backbone of the API and are likely backed by the same core CentrePoint data model used by the web portal.

4. **Subject-centric workflow**
   Several endpoints model the lifecycle of a subject in a study:
   studies contain sites, sites contain subjects, and subjects receive monitor assignments and uploads. The assignment workflow is explicitly separated from assignment retrieval, suggesting a stateful process for starting and ending device-to-subject tracking.

5. **Device and monitoring data**
   Activity monitors are first-class resources, along with the assignment workflow that links them to subjects. This is the bridge between study administration and captured device data, so a diagram should show device inventory and subject-device association as a distinct subsystem.

6. **Analytics and derived data**
   A separate group of endpoints serves processed study data: algorithm settings, minute summaries, daily statistics, sleep periods, and event markers. These are derived/analytics outputs rather than raw records, so they likely come from an analysis pipeline or precomputed store rather than direct transactional tables.

7. **Large-data and raw-data retrieval**
   The docs distinguish between “Data Access Files” for pre-made daily files of large raw accelerometer data and a legacy/raw data request flow for sub-second activity data. That implies a bulk-file generation subsystem or export service separate from the standard JSON resource endpoints.

8. **Export and dataset subsystem**
   The “DataSet Export” sections introduce study programs, datasets, dataset export files, and dataset export subjects. This is a second export-oriented boundary, focused on packaging study data for downstream analysis rather than operational management.

9. **Webhook/event delivery**
   Webhooks and webhook events provide a push-based integration path in addition to pull-based API access. The documentation covers both event listings and subscription/history tracking, which implies a notification dispatcher and request log/history service on the CentrePoint side.

10. **Operational constraints and protocol behavior**
   The API enforces request limiting at 500 requests per minute per IP with `429` and `Retry-After`, and uses ISO 8601 date handling with timezone semantics depending on the presence of `Z`. Pagination is documented separately, indicating list endpoints are expected to be consumed incrementally.

11. **File and upload handling**
   Uploads and visit files are separate from core JSON resources, which suggests mixed interaction modes: metadata via API and file transfer via dedicated endpoints. In a diagram, file-bearing flows should be shown apart from standard entity reads/writes.

12. **Repository structure as documentation map**
   The `sections/` directory is organized by capability area rather than by implementation layer, which makes the docs themselves a navigation index for the API surface. For architecture purposes, the sections map cleanly onto three major zones: operational study management, derived/analytics data, and data export/bulk transfer.

In short, the documentation describes a multi-surface integration platform centered on CentrePoint studies: authenticated JSON APIs for operational records, separate services for analytics and bulk data, and webhook-based outbound notifications.

Main entry points: [`sections/algorithm_settings.md`](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/algorithm_settings.md) (Algo Settings), [`sections/assignment_workflow.md`](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/assignment_workflow.md) (Assign Flow), [`README.md`](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/README.md) (API Guide), [`sections/authorization.md`](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/authorization.md) (OAuth Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs map"]
  node_readme["API Guide<br/>documentation<br/>[README.md]"]
end

subgraph group_edge["Integration edge"]
  node_auth(("OAuth Auth<br/>oauth2<br/>[authorization.md]"))
  node_api["API Surface<br/>json-api"]
end

subgraph group_ops["Operational study data"]
  node_studies["Studies<br/>study-admin<br/>[studies.md]"]
  node_sites["Sites<br/>study-ops<br/>[sites.md]"]
  node_subjects["Subjects<br/>study-ops<br/>[subjects.md]"]
  node_monitors["Monitors<br/>device-inventory"]
  node_assignflow{{"Assign Flow<br/>workflow"}}
  node_assignments["Assignments<br/>study-ops<br/>[assignments.md]"]
  node_milestones["Milestones<br/>study-ops"]
  node_uploads[("Uploads<br/>file-ingest<br/>[uploads.md]")]
  node_visitfiles[("Visit Files<br/>file-ingest<br/>[visit_files.md]")]
end

subgraph group_analytics["Derived analytics"]
  node_algos["Algo Settings<br/>analytics-config"]
  node_minute["Minute Summary<br/>derived-metrics<br/>[minute_summary.md]"]
  node_daily["Daily Stats<br/>derived-metrics"]
  node_sleep["Sleep Periods<br/>derived-analysis"]
  node_events["Event Markers<br/>derived-events<br/>[event_markers.md]"]
end

subgraph group_bulk["Bulk data export"]
  node_datafiles[("Data Access Files<br/>bulk-export")]
  node_epochreq["Epoch Requests<br/>raw-request"]
  node_epochfmt["Epoch Formats<br/>file-format"]
  node_rawreq["Raw Request<br/>raw-request"]
  node_rawfmt["Raw Formats<br/>file-format"]
  node_programs["Study Programs<br/>dataset-export<br/>[study_programs.md]"]
  node_datasets["Datasets<br/>dataset-export<br/>[data_set_files.md]"]
  node_dsubjects["Export Subjects<br/>dataset-export"]
end

subgraph group_notify["Notifications"]
  node_webhooks["Webhooks<br/>notification<br/>[webhooks.md]"]
  node_wevents["Webhook Events<br/>notification-log<br/>[webhook_events.md]"]
end

node_readme -->|"documents"| node_auth
node_readme -->|"maps to"| node_api
node_auth -->|"tokens for"| node_api
node_api -->|"exposes"| node_studies
node_studies -->|"contains"| node_sites
node_sites -->|"contains"| node_subjects
node_subjects -->|"uses"| node_assignflow
node_assignflow -->|"updates"| node_assignments
node_assignflow -->|"links"| node_monitors
node_api -->|"exposes"| node_milestones
node_api -->|"exposes"| node_uploads
node_api -->|"exposes"| node_visitfiles
node_api -->|"exposes"| node_algos
node_algos -->|"feeds"| node_minute
node_algos -->|"feeds"| node_daily
node_algos -->|"feeds"| node_sleep
node_algos -->|"feeds"| node_events
node_api -->|"exposes"| node_datafiles
node_api -->|"exposes"| node_epochreq
node_epochreq -->|"produces"| node_epochfmt
node_api -->|"exposes"| node_rawreq
node_rawreq -->|"produces"| node_rawfmt
node_api -->|"exposes"| node_programs
node_programs -->|"packages"| node_datasets
node_datasets -->|"includes"| node_dsubjects
node_api -->|"exposes"| node_webhooks
node_webhooks -->|"logs"| node_wevents

click node_readme "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/README.md"
click node_auth "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/authorization.md"
click node_studies "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/studies.md"
click node_sites "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/sites.md"
click node_subjects "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/subjects.md"
click node_monitors "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/activity_monitors.md"
click node_assignflow "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/assignment_workflow.md"
click node_assignments "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/assignments.md"
click node_milestones "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/study_milestones.md"
click node_uploads "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/uploads.md"
click node_visitfiles "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/visit_files.md"
click node_algos "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/algorithm_settings.md"
click node_minute "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/minute_summary.md"
click node_daily "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/daily_statistics.md"
click node_sleep "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/dustin_tracy_sleep_periods.md"
click node_events "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/event_markers.md"
click node_datafiles "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_access_files.md"
click node_epochreq "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/epoch_data_requests.md"
click node_epochfmt "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/epoch_data_file_formats.md"
click node_rawreq "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/raw_data_request.md"
click node_rawfmt "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/raw_data_file_formats.md"
click node_programs "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/study_programs.md"
click node_datasets "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_set_files.md"
click node_dsubjects "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_set_export_subjects.md"
click node_webhooks "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/webhooks.md"
click node_wevents "https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/webhook_events.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme toneBlue
class node_auth,node_api toneAmber
class node_studies,node_sites,node_subjects,node_monitors,node_assignflow,node_assignments,node_milestones,node_uploads,node_visitfiles toneMint
class node_algos,node_minute,node_daily,node_sleep,node_events toneRose
class node_datafiles,node_epochreq,node_epochfmt,node_rawreq,node_rawfmt,node_programs,node_datasets,node_dsubjects toneIndigo
class node_webhooks,node_wevents toneTeal
```

## Components

### Docs map

Documentation navigation and section organization

- [API Guide](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/README.md): documentation · Top-level documentation entry for the CentrePoint V3 API · `README.md`

### Integration edge

External clients authenticate and call hosted API endpoints

- [OAuth Auth](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/authorization.md): oauth2 · Token issuance and authorization endpoint · `sections/authorization.md`
- **API Surface**: json-api · Hosted JSON API for CentrePoint study administration

### Operational study data

Core study administration and subject/device workflows

- [Studies](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/studies.md): study-admin · Study-level resources and administration · `sections/studies.md`
- [Sites](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/sites.md): study-ops · Sites nested under studies · `sections/sites.md`
- [Subjects](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/subjects.md): study-ops · Subject records and lifecycle within a site or study · `sections/subjects.md`
- [Monitors](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/activity_monitors.md): device-inventory · Activity monitor resources · `sections/activity_monitors.md`
- [Assign Flow](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/assignment_workflow.md): workflow · Stateful assignment start and end workflow · `sections/assignment_workflow.md`
- [Assignments](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/assignments.md): study-ops · Assignment retrieval and assignment state records · `sections/assignments.md`
- [Milestones](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/study_milestones.md): study-ops · Study milestone tracking · `sections/study_milestones.md`
- [Uploads](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/uploads.md): file-ingest · File-bearing uploads associated with study records · `sections/uploads.md`
- [Visit Files](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/visit_files.md): file-ingest · Visit-scoped file resources · `sections/visit_files.md`

### Derived analytics

Processed metrics and computed study outputs

- [Algo Settings](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/algorithm_settings.md): analytics-config · Algorithm settings used by derived data outputs · `sections/algorithm_settings.md`
- [Minute Summary](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/minute_summary.md): derived-metrics · Minute-level computed summaries · `sections/minute_summary.md`
- [Daily Stats](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/daily_statistics.md): derived-metrics · Daily aggregated statistics · `sections/daily_statistics.md`
- [Sleep Periods](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/dustin_tracy_sleep_periods.md): derived-analysis · Computed sleep period results · `sections/dustin_tracy_sleep_periods.md`
- [Event Markers](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/event_markers.md): derived-events · Processed event marker data · `sections/event_markers.md`

### Bulk data export

Large-file and legacy/raw data delivery paths

- [Data Access Files](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_access_files.md): bulk-export · Pre-made daily files for large raw accelerometer data · `sections/data_access_files.md`
- [Epoch Requests](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/epoch_data_requests.md): raw-request · Legacy raw data request workflow · `sections/epoch_data_requests.md`
- [Epoch Formats](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/epoch_data_file_formats.md): file-format · Epoch data file format definitions · `sections/epoch_data_file_formats.md`
- [Raw Request](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/raw_data_request.md): raw-request · Raw sub-second activity data requests · `sections/raw_data_request.md`
- [Raw Formats](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/raw_data_file_formats.md): file-format · Raw data file format definitions · `sections/raw_data_file_formats.md`
- [Study Programs](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/study_programs.md): dataset-export · Programs used to group dataset export packaging · `sections/study_programs.md`
- [Datasets](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_set_files.md): dataset-export · Dataset definitions for downstream analysis packages · `sections/data_set_files.md`
- [Export Subjects](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/data_set_export_subjects.md): dataset-export · Subjects included in dataset exports · `sections/data_set_export_subjects.md`

### Notifications

Outbound webhook delivery and event history

- [Webhooks](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/webhooks.md): notification · Webhook subscriptions and delivery configuration · `sections/webhooks.md`
- [Webhook Events](https://github.com/actigraph/centrepoint3apidocumentation/blob/main/sections/webhook_events.md): notification-log · Webhook event listings and delivery history · `sections/webhook_events.md`

## Connections

- API Guide → OAuth Auth: documents · Documentation covers authorization first
- API Guide → API Surface: maps to · Top-level docs describe the hosted API surface
- OAuth Auth → API Surface: tokens for · OAuth tokens are required before API calls
- API Surface → Studies: exposes · Study administration resource family
- Studies → Sites: contains · Studies contain sites
- Sites → Subjects: contains · Sites contain subjects
- Subjects → Assign Flow: uses · Subject-device association is managed through the workflow
- Assign Flow → Assignments: updates · Workflow produces and closes assignment state
- Assign Flow → Monitors: links · Assignments connect monitors to subjects
- API Surface → Milestones: exposes · Study milestone endpoints
- API Surface → Uploads: exposes · Upload metadata and file transfer endpoints
- API Surface → Visit Files: exposes · Visit file resources
- API Surface → Algo Settings: exposes · Algorithm settings for derived outputs
- Algo Settings → Minute Summary: feeds · Settings influence minute summaries
- Algo Settings → Daily Stats: feeds · Settings influence daily statistics
- Algo Settings → Sleep Periods: feeds · Settings influence sleep period derivation
- Algo Settings → Event Markers: feeds · Settings influence event marker derivation
- API Surface → Data Access Files: exposes · Bulk data access file delivery
- API Surface → Epoch Requests: exposes · Legacy epoch data request workflow
- Epoch Requests → Epoch Formats: produces · Requests resolve to epoch data file formats
- API Surface → Raw Request: exposes · Raw sub-second data request workflow
- Raw Request → Raw Formats: produces · Requests resolve to raw data file formats
- API Surface → Study Programs: exposes · Dataset export program definitions
- Study Programs → Datasets: packages · Programs organize export datasets
- Datasets → Export Subjects: includes · Dataset exports enumerate included subjects
- API Surface → Webhooks: exposes · Webhook subscription API
- Webhooks → Webhook Events: logs · Webhook event history and delivery records