Frequently Asked Questions

Common questions and answers about Axiom Genesis platform development and usage.

General

What is Axiom Genesis?

Axiom Genesis is an enterprise-grade, multi-tenant workflow automation platform enabling visual page design, workflow orchestration, and dynamic data management. It uses a metadata-driven architecture where UI behavior, entity CRUD operations, and navigation are controlled by database configuration rather than hardcoded logic.

What technology stack does it use?

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Redux Toolkit, Tailwind CSS, MUI 7
Middleware	Node.js 18+, Express.js 4.x, MSSQL/PostgreSQL, Redis, Bull Queue
Documentation	Docusaurus 3.x

What databases are supported?

• MSSQL Server 2022+ (Primary)
• PostgreSQL 15+ (Supported)

Both databases use native JSON types (not NVARCHAR/TEXT for JSON storage).

---

Development

How do I set up the development environment?

# Clone and install
git clone <repository>
cd axiom-genesis
pnpm install

# Start all services
pnpm run dev

See the Installation Guide for detailed instructions.

How do I add a new entity/table?

1. Create the table in axiom-genesis-db/mssql/patches/
2. Register in app_object_registries with appropriate obj_code
3. Create profile in app_object_profiles with security policy
4. (Optional) Create DataView config in app_dataview_configs
5. (Optional) Add navigation entry in app_navigation_configs

See Database Documentation for schema conventions.

How do I add a custom API endpoint?

For entity CRUD operations, use the generic entity API (/api/v1/entity/:entity_code). Only add custom endpoints for operations that cannot be expressed through the entity API.

// routes/v1/custom.routes.js
router.get('/custom-endpoint', authenticate, async (req, res) => {
  // Custom logic here
});

Why isn't my DataView showing data?

Common causes:

1. Missing registry - Check app_object_registries has entry for obj_code
2. Missing profile - Check app_object_profiles has entry with prf_obj_code matching registry
3. Missing dataview config - Check app_dataview_configs has entry with correct dvc_obj_code
4. Tenant isolation - Ensure data has correct tenant_id

---

Architecture

What is the difference between Studio and Renderer?

Aspect	Studio (Design-time)	Renderer (Run-time)
Purpose	Configure artifacts	Present operational UI
Users	Admins, designers	End users
Actions	Save, version, publish	View, submit, interact
Data	Writes to config tables	Reads from config tables

How does multi-tenancy work?

Every request includes tenant context either via:

1. JWT token - For authenticated users, tenant_id is embedded in the token
2. x-tenant-id header - For pre-login requests, encrypted tenant ID in header

All database queries MUST include tenant filter:

WHERE xxx_tenant_id = @tenantId AND xxx_is_deleted = 0

What are object registries and profiles?

Component	Purpose
Object Registry (app_object_registries)	Defines entity metadata: table name, primary key, column prefix
Object Profile (app_object_profiles)	Defines security policy: field projection, masking, row filters

Profile code (prf_code) is used in API URLs, which maps to registry via prf_obj_code = obj_code.

---

Configuration

How do I add a new navigation menu item?

Insert into app_navigation_configs:

INSERT INTO app_navigation_configs (
  nvc_code, nvc_description, nvc_target_type, nvc_target_code,
  nvc_parent_code, nvc_icon, nvc_display_order, nvc_tenant_id
) VALUES (
  'nvc_my_item', 'My Menu Item', 'DATAVIEW', 'dvc_my_dataview',
  'nvc_parent', 'IconName', 10, @tenantId
);

How do I create a workflow?

1. Open Workflow Designer from admin menu
2. Drag nodes from palette to canvas
3. Connect nodes with edges
4. Configure node properties (triggers, actions, conditions)
5. Save draft, then publish

See Workflow Designer Guide for details.

How do I customize user preferences?

User preferences cascade: User Settings > Tenant Settings > System Defaults

Stored in:

• app_users.usr_app_settings - User-specific settings (JSON)
• app_tenants.tnt_app_settings - Tenant defaults (JSON)

---

Deployment

What are the startup modes?

The middleware supports three modes:

Mode	Command	Purpose
api	npm run start:api	HTTP server for REST API
worker	npm run start:worker	Background job processing
cron	npm run start:cron	Scheduled task execution

How do I deploy to Azure?

See the Readiness and Startup Guide for:

• App Service deployment
• Application Gateway setup
• Key Vault integration
• Container configuration

How do I clear the Redis cache?

# Clear all caches
redis-cli FLUSHDB

# Clear specific cache pattern
redis-cli KEYS "obj_registry:*" | xargs redis-cli DEL

---

Troubleshooting

Where can I find error logs?

Component	Location
Middleware	Console output, Azure Log Analytics
Frontend	Browser console, Next.js logs
Database	MSSQL error log, wft_logs table

How do I debug a failed workflow?

-- Get workflow instance details
SELECT * FROM wft_instances WHERE wfi_id = @instanceId;

-- Get execution logs
SELECT * FROM wft_logs WHERE wfl_instance_id = @instanceId ORDER BY wfl_created_at;

-- Get node states
SELECT * FROM wft_node_states WHERE wns_instance_id = @instanceId;

See Troubleshooting Guide for more details.

---

Contributing

How do I contribute to documentation?

1. Fork the repository
2. Edit files in axiom-genesis-guide/docs/
3. Run npm run build to verify no broken links
4. Submit a pull request

What naming conventions should I follow?

Type	Convention	Example
Files	lowercase-kebab-case	page-designer.md
Tables	app_ or apt_ or wft_ prefix	app_users
Columns	3-letter prefix	usr_email_id
Components	PascalCase	FormRenderer.tsx
Services	kebab-case with .service	record.service.ts