- 🧭 Executive Summary
- 🎯 Application Purpose
- 🏢 Business Architecture
- ✨ Application Features
- 🏗️ Technical Architecture
- 🔄 Technical Flow Map
- 🗃️ Data Architecture
- 🧩 Product Offering
- 📄 License
SpectraSurvey is a multi-tenant platform designed for:
- creating, distributing, and analyzing surveys,
- managing organizational files through storage, sharing, and versioning,
- enabling team and organization administration with audit and compliance visibility,
- supporting centralized super-admin operations across tenants.
Provide organizations with a unified system for:
- survey operations,
- associated data and digital asset management,
- controlled collaboration,
- compliance visibility and governance.
- 📬 Improve response rates through multi-channel distribution and optimized public UX.
- 🧾 Provide traceability through audit and compliance visibility for enterprise and regulated use cases.
- 🗂️ Centralize survey data and digital assets in one operational workspace.
- 🏢 Support multi-tenant organizational administration with role-based control.
- 📊 Enable insight generation through survey analytics and response exploration.
- Organization Member: creates surveys, analyzes results, manages files.
- Organization Admin: manages members, policies, settings, and access.
- Platform Super Admin: governs tenants, users, and global configurations.
- Respondent (External/Public): completes surveys through public or private access flows.
- Research Operations: survey design, publishing, response collection.
- Analytics & Insight: dashboards, exports, response-level analysis.
- Digital Asset Management: folders, files, versions, sharing, trash.
- Tenant Administration: members, roles, organization settings.
- Platform Governance: global admin, monitoring, compliance controls.
flowchart LR
A["Respondent"] --> B["Public Survey Access"];
B --> C["Survey Engine"];
C --> D["Analytics"];
C --> E["Audit Trail"];
F["Organization Member"] --> C;
F --> G["File Governance"];
H["Organization Admin"] --> I["Tenant Settings"];
H --> J["Team Management"];
K["Super Admin"] --> L["Platform Control Plane"];
L --> M["Organizations"];
L --> N["Users"];
L --> O["Compliance / Monitoring"];
- 🔐 Login, signup, reset, and MFA flow.
- 👤 Separate contexts for standard users and super-admin.
- 🕓 Login history and security event visibility.
- ✉️ Organization confirmation and invite flows.
- 🚦 Rate limiting on authentication endpoints.
- 📝 Create, edit, and delete surveys.
- 🧱 Question builder with types, logic, and ordering.
- 🗓️ Scheduling and lifecycle controls (start, end, archive, trash).
- 💾 Auto-save draft and recovery support.
- 🌍 Public survey pages with access guards.
- 🔒 Password-protected surveys and additional validation flows.
- 👥 Invitation-based and group-based distribution.
- 🛡️ Anti-abuse controls such as captcha or challenge flows where applicable.
- 📊 Overview dashboard and response trends.
- 🔎 Individual response inspection.
- 🔁 Cross-survey comparisons.
- 📤 Export options such as CSV, Excel, and PDF where enabled.
- 🧩 Audience segmentation through groups.
- ✉️ Invitation lifecycle: send, resend, expire, complete.
- 🔗 Share links and QR-based distribution.
- 📁 Folder and file hierarchy.
- 🕘 File versioning with auto/manual version history.
- 🔐 Secure sharing options:
- expiration,
- maximum downloads,
- password protection,
- email delivery.
- 👥 Team invite, remove, and role change flows.
- 🔐 Per-user MFA toggle.
- 🎨 Organization branding such as name and logo.
- ⚙️ Organization-level policies and settings.
- 🏢 Organization management.
- 👤 User management and privilege elevation.
- 📈 Platform reports and global controls.
- 📝 Release notes and version management.
- 🛡️ Global audit and compliance views.
- 📋 Activity logs by organization.
- 🚨 Security event timeline.
- 🔑 Login history views.
- 💓 Operational telemetry and health visibility.
- Frontend: React + TypeScript + Vite.
- UI / Routing: React Router, modular domain pages.
- Backend API: Node.js + Express + security middleware.
- Database: MySQL
flowchart TD
Browser["Browser / SPA"] --> FE["React Frontend"];
FE --> API["Express API /api & /api/v2"];
API --> DB["MySQL"];
API --> FS["Local File Storage"];
API --> Workers["Background Workers"];
Workers --> Email["Email Notifications"];
- 🧭 Domain-oriented pages in
src/pages/* - 🧩 Reusable UI components in
src/components/* - 🔌 API and services layer in
src/services/* - 🪝 Hooks for data fetching and mutations in
src/hooks/*
- Auth, session, and token flows.
- Survey management and public submission endpoints.
- File, folder, version, and share endpoints.
- Organization, member, and role endpoints.
- Audit, security, and admin routes.
- Worker jobs for backups, cleanup, and observability.
sequenceDiagram
participant User
participant Frontend
participant API
participant DB
User->>Frontend: Submit credentials
Frontend->>API: POST /api/auth/login
API->>DB: Validate user + membership
DB-->>API: User + org context
API-->>Frontend: Session cookies / auth response
Frontend-->>User: Authenticated session
sequenceDiagram
participant Respondent
participant Frontend
participant API
participant DB
Respondent->>Frontend: Open public survey URL
Frontend->>API: GET /api/v2/public/surveys/:id
API->>DB: Validate visibility and schedule
DB-->>API: Survey payload
API-->>Frontend: Survey + questions
Respondent->>Frontend: Submit answers
Frontend->>API: POST /api/v2/public/surveys/:id/submit
API->>DB: Persist response + audit/security events
API-->>Frontend: Submission success
sequenceDiagram
participant User
participant Frontend
participant API
participant Storage
User->>Frontend: Create share link
Frontend->>API: POST /api/files/:id/share
API->>API: Apply ACL, expiry, and download limits
API-->>Frontend: Signed/public link metadata
Respondent->>API: GET shared file endpoint
API->>Storage: Validate link + stream file
API-->>Respondent: File download
- Identity and Access: users, organization memberships, roles.
- Survey Domain: surveys, questions, responses, invitations.
- File Domain: folders, files, versions, shares, logs.
- Governance Domain: audit logs, security events, cron logs, reports.
erDiagram
ORGANIZATIONS ||--o{ USERS : has
ORGANIZATIONS ||--o{ SURVEYS : owns
SURVEYS ||--o{ SURVEY_QUESTIONS : contains
SURVEYS ||--o{ SURVEY_RESPONSES : receives
ORGANIZATIONS ||--o{ FILES : owns
FILES ||--o{ FILE_VERSIONS : versions
ORGANIZATIONS ||--o{ AUDIT_LOGS : emits
ORGANIZATIONS ||--o{ SECURITY_EVENTS : emits
- Most domains are organization-scoped.
- Isolation is implemented through schema structure and server-side access checks.
- Strict regression testing is required for every tenant route and hook to avoid cross-organization leakage.
- Research Engine: advanced survey creation and execution.
- Insight Engine: analytics and reporting.
- Collaboration Engine: teams, roles, organization settings.
- File Governance Engine: secure file management and sharing.
- Control Plane: global admin, audit, compliance, and monitoring.
Distributed under the Proprietary License. See LICENSE for more information.
**Built with ❤️ by the SpectraEYE Team**