System Architecture

Overview

OCTAVIUS implements a three-tier client-server architecture with separation of concerns between presentation, application logic, and data persistence layers.

Component Architecture

API Layer

Technology: Node.js with Express.js framework

Responsibilities:

• Exposing RESTful endpoints for client-server communication
• Implementing complex logic through resolver functions
• Managing database connectivity and query execution
• Authentication and authorization middleware.

Key Directories:

• api/resolvers/ — Complex logic handlers for API requests
• api/db/ — Data access methods and MongoDB model definitions
• api/startup/ — Application initialization and configuration
• api/server.js — Main entry point and middleware configuration

Presentation Layer

Technology: React single-page application (created via Create React App)

Responsibilities:

• Rendering dynamic user interfaces
• Managing client-side state and routing
• Formatting and validation of user input
• Asynchronous API communication

Key Directories:

• ui/src/Routes/ — Page components and route definitions
• ui/src/Components/ — Reusable UI components (headers, tables, icons, etc.)
• ui/src/Methods/ — API client helper functions
• ui/src/Utils/ — Utility functions for formatting, data transformation, and async operations

Data Persistence Layer

Technology: MongoDB document database within a containerized environment

Responsibilities:

• Persistent storage of survey data, user records, and classifications
• Index management for query optimization
• Transactions and validation at the schema level

Deployment: Containerized MongoDB initialized via BSON dumps in docker/mongo-init/

Data Flow

The following sequence describes a typical request-response cycle:

1. Client Request: The React UI component generates an HTTP request to the API server
2. Route Resolution: Express middleware routes the request to the appropriate resolver function
3. Business Logic: The resolver executes validations and orchestrates database queries via data access methods
4. Database Query: MongoDB executes the query with appropriate indexes and constraints
5. Response Construction: The API aggregates database results, applies transformations if needed, and serializes the response
6. Client Reception: React receives the promise-resolved data and updates component state
7. Rendering: The component re-renders with updated data, reflecting changes in the user interface

Service Architecture

Docker Compose Orchestration

The system supports containerized deployment via Docker Compose, which orchestrates three services:

• api — Node.js application server (Express)
• ui — React development/production server
• mongo — MongoDB document database

This configuration enables reproducible deployments across development, testing, and production environments.

Code Entry Points

Begin exploring the codebase at these primary entry points: (Not if you are currently in the public Pages, these links will not work)

• API Initialization: api/server.js — Server configuration, middleware setup, and route definitions
• Frontend Bootstrap: ui/src/index.js — React DOM rendering and application root
• Database Configuration: docker/docker-compose.yml — Service orchestration and MongoDB initialization