Docyrus App Developer

Build React TypeScript web apps with Docyrus as the backend. Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and follow established patterns.

Tech Stack

• React 19 + TypeScript + Vite
• TanStack Router (code-based), TanStack Query (server state)
• Tailwind CSS v4, shadcn/ui components
• @docyrus/api-client (REST client) + @docyrus/signin (auth provider)
• Auto-generated collections from OpenAPI spec

Quick Start: New App Setup

1. Wrap root with DocyrusAuthProvider:

import { DocyrusAuthProvider } from '@docyrus/signin'

<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <QueryClientProvider client={queryClient}>
    <RouterProvider router={router} />
  </QueryClientProvider>
</DocyrusAuthProvider>

2. In App.tsx, check auth and use collection hooks:

const { status } = useDocyrusAuth()
const { getMyInfo } = useUsersCollection()

if (status === 'loading') return <Spinner />
if (status === 'unauthenticated') return <SignInButton />

3. Use collection hooks in components:

const { list } = useBaseProjectCollection()

const { data: projects } = useQuery({
  queryKey: ['projects'],
  queryFn: () => list({
    columns: ['name', 'status', 'record_owner(firstname,lastname)'],
    filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
    orderBy: 'created_on DESC',
    limit: 50,
  }),
})

Critical Rules

1. Always send columns in .list() and .get() calls. Without it, only id is returned.
2. Collections are React hooks — call useBaseProjectCollection(), useUsersCollection(), etc. inside React components. They use useDocyrusClient() internally for authenticated API access.
3. Data source endpoints are dynamic — they only exist if the data source is defined in the tenant's OpenAPI spec.
4. Use id field for count calculations. Use the actual field slug for sum, avg, min, max.
5. Child query keys must appear in columns — e.g., if childQuery key is orders, include 'orders' in the columns array.
6. Formula keys must appear in columns — e.g., if formula key is total, include 'total' in the columns array.
7. Use useUsersCollection().getMyInfo() for current user profile, not a direct API call.

Regenerating Collections After Schema Changes

When data sources or fields are created, updated, or deleted via the docyrus-architect MCP tools, the app's auto-generated collections become stale. To resync:

1. Call regenerate_openapi_spec (architect MCP) to rebuild and upload the tenant's OpenAPI spec
2. Download the new spec into the repo, overwriting the existing file:

   curl -o openapi.json "<publicUrl returned from step 1>"
   

3. Regenerate collections:

   pnpx @docyrus/tanstack-db-generator openapi.json
   

Always run all three steps together — a stale openapi.json or outdated collections will cause missing or incorrect endpoints at runtime.

Collection CRUD Methods

Every generated collection is a React hook that returns CRUD methods:

const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()

list(params?: ICollectionListParams)   // Query with filters, sort, pagination
get(id, { columns })                    // Single record
create(data)                            // Create
update(id, data)                        // Partial update
deleteOne(id)                           // Delete one
deleteMany({ recordIds })               // Delete many

API endpoint pattern: /v1/apps/{appSlug}/data-sources/{slug}/items

Query Capabilities Summary

The .list() method supports:

Feature	Purpose
columns	Select fields, expand relations field(subfields), alias alias:field, spread ...field()
filters	Nested AND/OR groups with 50+ operators (comparison, date shortcuts, user-related)
filterKeyword	Full-text search
orderBy	Sort by fields with direction, including related fields
limit/offset	Pagination (default 100)
fullCount	Return total count alongside results
calculations	Aggregations: count, sum, avg, min, max with grouping
formulas	Computed virtual columns (simple functions, block AST, correlated subqueries)
childQueries	Fetch related child records as nested JSON arrays
pivot	Cross-tab matrix queries with date range series
expand	Return full objects for relation/user/enum fields instead of IDs

For query/formula details, read:

• references/data-source-query-guide.md
• references/formula-design-guide-llm.md

TanStack Query Pattern

// Query hook — call collection hook inside the component, pass methods to TanStack Query
function useProjects(params?: ICollectionListParams) {
  const { list } = useBaseProjectCollection()
  return useQuery({
    queryKey: ['projects', 'list', params],
    queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
  })
}

// Mutation hook
function useCreateProject() {
  const { create } = useBaseProjectCollection()
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (data: Record<string, unknown>) => create(data),
    onSuccess: () => { void qc.invalidateQueries({ queryKey: ['projects'] }) },
  })
}

References

Read these files when you need detailed information:

• references/api-client-and-auth.md — RestApiClient API, @docyrus/signin hooks, auth provider config, interceptors, error handling, SSE/streaming, file upload/download
• references/data-source-query-guide.md — Up-to-date query payload guide: columns, filters, orderBy, pagination, calculations, formulas, child queries, pivots, and operator reference
• references/formula-design-guide-llm.md — Up-to-date formula design guide for building and validating formulas payloads
• references/collections-and-patterns.md — Generated collection hooks, useUsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints