Revision file generation

What is design_versions.json?

design_versions.json is a JSON file that contains an array of design version objects, each with a chunk ID and its revision count value.

Data Structure

[
  { "chunk_id": <design version chunk_id>, "revision_count": <current design version revision_count value> },
  { "chunk_id": <design version chunk_id>, "revision_count": <current design version revision_count value> },
  ...
]

Example:

[
  { "chunk_id": 12345, "revision_count": 5 },
  { "chunk_id": 67890, "revision_count": 12 },
  { "chunk_id": 11223, "revision_count": 3 }
]

Each array item contains:

• chunk_id: The design version’s chunk_id field from the database
• revision_count: The current design version’s revision_count value from the database

Why Do We Need It?

The 3D Desktop App uses this file to manage local caching and determine when to re-download design versions.

Cache Management Flow

1. First time: 3D App downloads a design version and caches it locally
2. Subsequent launches: 3D App checks design_versions.json
3. If revision_count changed: App re-downloads the design version (new changes available)
4. If revision_count unchanged: App uses cached version (faster load time)

Where to Access It?

Direct S3 URL

https://app-catalog-rdesign.s3.amazonaws.com/design_versions.json

You can access this URL directly in your browser to view the current file contents.

AppVersion API Response

The file URL is also provided via the AppVersion API response:

{
  "design_versions_url": "https://app-catalog-rdesign.s3.amazonaws.com/design_versions.json",
  ...
}

The 3D App fetches the URL from this API field dynamically.

When is the File Generated?

When to Regenerate

You should regenerate design_versions.json when:

• New design versions are published
• Existing design versions are updated (revision_count changed)
• Design versions are activated/deactivated
• After bulk design version updates

How to Generate the File

Access the Admin Settings Page

1. Log in to the admin dashboard
2. Navigate to Admin Settings
3. Find the “Generate design_versions.json” button

Generation Process

When you click the generate button, the system:

1. Fetches all active design versions where revision_count is NOT NULL
2. Extracts the chunk_id field from each design version
3. Builds the JSON data structure (chunk_id → revision_count mapping)
4. Uploads the generated file to AWS S3
5. Makes it available at the S3 URL

Data Filtering Rules

The system only includes design versions that meet ALL of these criteria:

• ✅ Status is active
• ✅ revision_count field is NOT NULL
• ✅ chunk_id field exists

Technical Specifications

File Format

• Format: JSON
• Content-Type: application/json
• Encoding: UTF-8
• Structure: Array of objects with chunk_id and revision_count fields

S3 Storage Details

• Bucket: app-catalog-rdesign
• Object Key: design_versions.json
• Access: Public read
• CDN: Served via CloudFront (if configured)

Database Query Logic

The generation process executes a query similar to:

SELECT chunk_id, revision_count 
FROM design_versions 
WHERE status = 'active' 
  AND revision_count IS NOT NULL
  AND chunk_id IS NOT NULL

Troubleshooting

Problem: 3D App Not Downloading Updated Design Versions

Possible Causes:

1. design_versions.json was not regenerated after updates
2. revision_count was not incremented in the database
3. S3 file upload failed
4. CDN cache not cleared (if using CloudFront)

Solution:

1. Verify revision_count was incremented in database
2. Regenerate design_versions.json via admin settings
3. Check S3 to confirm file was uploaded
4. Clear CDN cache if applicable
5. Test by downloading the S3 URL directly

Problem: File Generation Failed

Possible Causes:

1. AWS S3 credentials invalid or expired
2. Insufficient S3 bucket permissions
3. Database connection issues

Solution:

1. Check Heroku environment variables for AWS credentials
2. Verify S3 bucket permissions (PutObject)
3. Check application logs for error messages
4. Contact backend team if issue persists

Related Systems

Design Version Management

• Design versions are managed in the design_versions table
• Each update should increment the revision_count field
• Only active design versions with non-null revision counts are included

3D Desktop App Integration

• App fetches design_versions_url from AppVersion API on launch
• Downloads and parses the JSON file
• Compares local cache revision counts with file values
• Re-downloads only changed design versions

AWS S3

• File stored in app-catalog-rdesign bucket
• Public read access required for 3D App downloads
• Upload handled automatically by the generate button

Best Practices

1. Regular Updates

2. Verification After Generation

After generating the file:

1. Download it directly from the S3 URL
2. Verify the file is valid JSON
3. Check that updated design versions are included
4. Confirm revision counts match the database

3. Communication

When regenerating the file:

• Notify the team in relevant Slack channels
• Document what changes were included
• Note the timestamp for reference

4. Monitoring

Regularly monitor:

• File accessibility (S3 URL returns 200 OK)
• File size (sudden changes may indicate issues)
• Last modified date (should match last generation)

Future Improvements

Related Documents

Internal Documentation

• System Architecture Overview
• Member & Plan System

External Documentation

• AWS S3 Documentation
• Design Version Management Guide (to be created)

Update History

• January 5, 2026: Initial version created