opsxsql/docs/frontend-architecture.md

Frontend Architecture

OpsxSQL frontend uses a light domain-first structure:

• pages: route-level composition only
• features: business domains such as datasource, Redis, Mongo, query, ticket, RBAC, governance, system
• api: transport clients grouped by backend domain
• components: existing shared app components
• shared: new cross-domain primitives

Production guideline:

• Keep page files below about 700 lines.
• Move reusable business UI into features/<domain>/components.
• Move domain state/data orchestration into features/<domain>/hooks.
• Move cross-domain helpers into shared/lib.
• Avoid putting transport logic inside components.
• New API imports should prefer domain paths such as api/datasource/redis and api/system/user; top-level API files are compatibility shims.
• Database-engine-specific behavior belongs under features/datasource/engines/<engine> or the engine domain (features/redis, features/mongo) when the surface is large enough.

Domain map:

• features/datasource: instance inventory, connection forms, import flows, MySQL/PostgreSQL engine panels
• features/redis: Redis key/value browsing, Redis result formatting, Redis command helpers
• features/mongo: MongoDB collection/document browsing and Mongo shell result rendering
• features/query: self-service query workspace, templates, query history, result rendering
• features/ticket: change ticket lifecycle, execution, rollback, approval actions
• features/governance: workflows, audit rules, risk policy, execution windows, SLA policy
• features/rbac: users, roles, permission groups, LDAP sync
• features/system: settings, notifications, announcements, audit logs, appearance

First migration sample:

• Redis value formatting and command helpers now live in features/redis.
• Redis Hash result display is shared by Redis detail and query workflows.
• Query template/history UI now lives in features/query.

Current page-size hotspots:

• InstancePage.tsx: datasource domain
• UsersPage.tsx: RBAC domain
• TicketsPage.tsx and TicketDetailPage.tsx: ticket domain
• WorkflowPage.tsx: governance domain
• LdapConfigPage.tsx: RBAC/system boundary; should be folded into RBAC LDAP panels or system integration settings

Use npm run audit:pages in frontend/ to find pages over the 700-line budget.