How selisedigitalplatforms/blocks-construct-react works
1. Overall shape
- This repository is a client-side React SPA for SELISE <blocks /> Construct.
- It is organized as a feature/module-based frontend blueprint rather than a single vertical app. Most business behavior lives under src/modules/*, while shared infrastructure and primitives live under src/lib, src/state, src/components, and src/layout.
2. Application shell
- The runtime entry is src/index.tsx, which boots the app and wires global providers.
- src/App.tsx and src/routes/* define the top-level route composition.
- Two major layout shells exist:
- src/layout/auth-layout for login/activation/reset flows
- src/layout/main-layout for authenticated application pages
- This creates a clear boundary between public/authentication journeys and the protected product UI.
3. Routing and access control
- Route definitions are centralized in src/routes/app-routes.tsx, auth.route.tsx, and route.tsx.
- Auth protection is handled in src/state/store/auth/* with guard/protected-route logic.
- src/constant/auth-public-routes.ts and related constants define which paths are accessible before sign-in.
- The architecture is therefore route-driven, with authorization enforced at the router boundary rather than inside every feature.
4. State and server-data orchestration
- Global state is split between:
- src/state/store/auth for authentication/session state
- src/state/query-client for server-state/query orchestration
- src/state/client-middleware.tsx for cross-cutting client concerns
- Custom hooks in src/hooks/* expose reusable UI and state behaviors such as language switching, toast handling, media queries, filters, popover sizing, and OTP resend.
- The app follows a pattern where pages compose hooks + services + presentational components, with server data cached and managed centrally.
5. Data access layer
- src/lib/graphql-client.ts and src/lib/https.ts are the primary integration points for backend communication.
- Many modules have their own services/*, graphql/*, types/*, and sometimes hooks/*, indicating a modular service boundary per domain.
- The README positions this repo as pre-integrated with SELISE Blocks Cloud services; in practice, the app talks to external microservices rather than hosting its own backend.
- Data flow is typically: page/component → feature hook → feature service / GraphQL query / HTTP call → external blocks service.
6. Authentication and identity
- The src/modules/auth area handles sign-in, signup, password reset, account activation, OTP verification, SSO, and OIDC callback flows.
- It includes dedicated services (auth.service.ts, sso.service.ts) and multiple page-level entry points for different auth states.
- Supporting shared pieces like CAPTCHA (src/components/core/captcha), password inputs, OTP inputs, and confirmation modals are reused across these flows.
- This module is the key boundary for identity establishment before the main app shell is entered.
7. Shared UI foundation
- src/components/ui-kit contains low-level design system primitives: buttons, dialogs, inputs, tables, tabs, toasts, sidebars, tooltips, etc.
- src/components/core builds higher-level reusable application components on top of the UI kit, such as:
- navigation and chrome elements
- data-table abstractions
- language/theme selectors
- notifications
- password and OTP forms
- dynamic breadcrumbs, avatars, and banners
- This creates a layered UI model: UI kit → core composites → feature-specific components.
8. Feature modules
- The largest architectural unit is the feature module under src/modules/*.
- Each module is mostly self-contained with its own pages, components, hooks, services, types, and utilities.
- Major domains include:
- dashboard
- finance
- invoices
- inventory
- task manager
- calendar
- chat
- file manager
- profile / IAM / users
- activity log
- error views
- These modules are good candidates for diagram boxes because each one encapsulates a business capability and its own internal UI/data flow.
9. Domain-specific patterns
- Several domains use GraphQL-first CRUD workflows explicitly, especially inventory, invoices, and task manager.
- Others are more UI-driven but still service-backed, such as chat, email, file management, and calendar.
- Many domains expose a page-level container plus nested components for lists, details, toolbars, filters, drawers/sheets, and modals.
- This means the UI is generally organized by screen + interaction surface, not by purely atomic components.
10. Cross-cutting UX concerns
- Internationalization is handled in src/i18n/*, including route-module mappings and translation loading.
- Theming is centralized in src/styles/theme/theme-provider.tsx, with global styles in src/styles/globals.css.
- Responsive behavior is supported by shared hooks/utilities and many module-specific mobile variants.
- Notifications, confirmation dialogs, loading overlays, and error views are shared UX boundaries used across features.
11. Specialized product capabilities
- Some modules indicate deeper product workflows:
- profile includes MFA, sessions, devices, and account/security management
- file-manager supports my files, shared files, trash, grid/list views, file details, and mock-query hooks
- big-calendar includes event creation/editing, recurrence handling, filters, and settings context
- task-manager supports card/list views, drag-and-drop-like interactions, details panels, comments, tags, and columns
- These features are not simple CRUD screens; they are richer interaction subsystems with dedicated state and UI coordination.
12. External services and integrations
- The project is built around SELISE Blocks Cloud and its microservices ecosystem.
- CAPTCHA support is configurable for reCAPTCHA or hCaptcha via environment variables.
- SSO/OIDC integration is explicit in the auth module, and multi-organization/storage APIs exist under src/lib/api.
- The app therefore sits as a frontend orchestration layer above multiple external identity, storage, and domain services.
13. Build, deployment, and delivery
- The repo uses Vite + TypeScript + React with Tailwind/PostCSS styling.
- It is designed for static deployment, with nginx.conf, Dockerfile, staticwebapp.config.json, and swa-cli.config.json indicating container/static-host deployment paths.
- CI/CD is handled through GitHub Actions workflows for testing, Sonar analysis, dev/staging/web builds, and Storybook.
- This matters architecturally because the runtime is a static frontend bundle, not a server-rendered app.
14. What to draw in an architecture diagram
- Put the app at the center as a React SPA shell.
- Show a top layer for routing/layout/auth protection.
- Under that, show shared platform services: theme, i18n, state/query client, GraphQL/HTTP client.
- Surround those with feature modules as separate bounded contexts.
- Draw outbound connections from modules to Blocks Cloud microservices, auth/SSO/CAPTCHA providers, and storage/organization APIs.
- Add a deployment lane for static hosting/containerization and CI/CD tooling.
Main entry points: App.tsx App · https.ts HTTP Client · app-routes.tsx Routes · graphql-client.ts GraphQL Client
Components 33
App Shell
Runtime entry, route composition, layouts, and access control.
- Entry · Bootstraps the SPA and mounts global providers.
src/index.tsx - App · Top-level application composition.
src/App.tsx - Routes · Central route definitions for auth and product pages.
src/routes/app-routes.tsx - Auth Shell · Layout for sign-in, activation, reset, and SSO journeys.
src/layout/auth-layout/auth-layout.tsx - Main Shell · Authenticated application chrome and navigation shell.
src/layout/main-layout/main-layout.tsx - Auth Guard · Protected-route and guard logic around authenticated access.
src/state/store/auth/protected-route.tsx
Shared Platform
Cross-cutting state, clients, styling, and reusable UI foundations.
- Query Client · Central server-state and caching orchestration.
src/state/query-client/index.tsx - Auth State · Authentication/session state used by guards and protected UI.
src/state/store/auth/index.tsx - Client Middleware · Cross-cutting client-side middleware and orchestration.
src/state/client-middleware.tsx - i18n · Language loading and route-module translation mapping.
src/i18n/i18n.ts - Theme · Theme provider and global styling foundation.
src/styles/theme/theme-provider.tsx - UI Kit · Low-level reusable primitives such as inputs, dialogs, tables, and toasts.
src/components/ui-kit/button.tsx - Core UI · Higher-level application components built on the UI kit.
src/components/core/index.ts - GraphQL Client · Primary GraphQL integration point for feature modules.
src/lib/graphql-client.ts - HTTP Client · Primary HTTP integration point for feature modules.
src/lib/https.ts
Feature Modules
Major self-contained product domains and workflows.
- Identity · Sign-in, signup, activation, password reset, SSO, and OIDC flows.
src/modules/auth/services/auth.service.ts - Dashboard · Home dashboard with metrics, charts, and summary cards.
src/modules/dashboard/index.ts - Finance · Financial overview, revenue/expense graphs, and invoice summaries.
src/modules/finance/index.ts - Invoices · Invoice list, details, creation, editing, and GraphQL-driven workflows.
src/modules/invoices/index.ts - Inventory · Inventory listing, forms, details, filters, and GraphQL queries/mutations.
src/modules/inventory/index.ts - Tasks · Card/list task management with details, tags, columns, and drag-like interactions.
src/modules/task-manager/index.ts - Calendar · Big calendar with events, recurrence, filters, and settings.
src/modules/big-calendar/index.ts - Chat · Conversation UI, contacts, message actions, and group tooling.
src/modules/chat/index.ts - Email · Mailbox, compose, reading, actions, and responsive email views.
src/modules/email/index.ts - Files · My files, shared files, trash, previews, filters, and details panes.
src/modules/file-manager/index.ts - Profile · Profile, security, MFA, sessions, devices, and account settings.
src/modules/profile/index.ts - IAM · User management, profile administration, and table-driven user workflows.
src/modules/iam/index.ts - Activity · Activity log timelines and grouped activity views.
src/modules/activity-log/index.ts - Errors · Not found, unauthorized, and service-unavailable experiences.
src/modules/error-view/index.ts
Delivery & Integrations
Static deployment and external service boundaries.
- Blocks Cloud · External SELISE Blocks Cloud microservices consumed by the frontend.
- Auth Providers · SSO, OIDC, and CAPTCHA providers used during authentication.
- Storage API · Multi-org and storage APIs used by the file manager and related flows.
src/lib/api - Static Deploy · Vite-built SPA packaged for nginx, Docker, and static hosting.
Dockerfile
Connections 30
- Entry → App: boots · Entry mounts the root application.
- App → Routes: composes · App delegates page composition to routes.
- Routes → Auth Shell: public shell · Auth routes render through the public layout.
- Routes → Main Shell: app shell · Protected routes render through the main layout.
- Routes → Auth Guard: protects · Route boundary enforces authentication.
- Auth Guard → Auth State: reads · Guard checks session state.
- App → Query Client: provides · Global server-state client is wired at the app level.
- App → Client Middleware: wraps · Client middleware handles cross-cutting concerns.
- App → i18n: localizes · Application loads translations and language context.
- App → Theme: themes · Theme provider sets global look and feel.
- Main Shell → Core UI: uses · Main shell composes shared chrome and navigation.
- Core UI → UI Kit: builds on · Core components are assembled from primitives.
- Identity → Auth State: updates · Authentication flows persist session state.
- Identity → Auth Providers: authenticates · SSO/OIDC and CAPTCHA flows reach external identity providers.
- Identity → HTTP Client: calls · Auth services communicate via HTTP.
- Dashboard → GraphQL Client: reads · Dashboard data is fetched from backend services.
- Finance → GraphQL Client: reads · Finance metrics and graphs consume backend data.
- Invoices → GraphQL Client: CRUD · Invoices module uses GraphQL queries and mutations.
- Inventory → GraphQL Client: CRUD · Inventory module is GraphQL-first.
- Tasks → GraphQL Client: CRUD · Task manager persists and queries task data.
- Calendar → HTTP Client: syncs · Calendar workflows use service-backed calls.
- Chat → HTTP Client: syncs · Chat features integrate through backend services.
- Email → HTTP Client: syncs · Email state and actions are service-backed.
- Files → Storage API: manages · File manager uses multi-org and storage APIs.
- Profile → HTTP Client: manages · Profile and security features call account and MFA services.
- IAM → HTTP Client: manages · IAM user administration uses backend services.
- Activity → HTTP Client: reads · Activity timelines are fetched from services.
- Errors → Routes: fallbacks · Error pages are used as route-level fallbacks.
- Static Deploy → Entry: packages · Static delivery packages the SPA bundle.
- Static Deploy → Blocks Cloud: serves · Frontend is deployed against external Blocks Cloud services.