About EnneadTab

Why We Need This Webapp

EnneadTab BIM Data was created to solve the critical challenge of tracking and analyzing Revit project data across multiple projects and teams. Traditional methods of monitoring Revit model health are manual, time-consuming, and lack centralized visibility. As projects grow and teams expand, the need for automated, scalable analytics becomes essential.

This webapp provides a centralized dashboard for:

Real-time tracking of Revit model metrics and health scores across all projects
Historical data analysis and trend identification over time
Automated data collection from Revit extraction scripts
Centralized visibility across all hubs, projects, and models
Dynamic scoring based on current best practices (algorithm updates without data migration)
Scalable architecture designed for weekly data tracking and long-term growth

Architecture & Design Decisions

Facts Only Storage - Dynamic Scoring

One of the most important architectural decisions was to store only raw facts in the database, not computed scores. This "facts only" approach provides several key benefits:

Algorithm Flexibility: Scoring algorithms can be updated without database migrations or data reprocessing
Single Source of Truth: Raw data remains unchanged, ensuring consistency and auditability
Future-Proof: New scoring methodologies can be implemented without touching stored data
Performance: Scores are calculated on-demand, ensuring users always see results based on the latest algorithm

Hybrid Schema Design

The database schema uses a hybrid approach that balances performance with flexibility:

Normalized Metadata: Core fields (hub_name, project_name, model_name, timestamp) are normalized for efficient querying, filtering, and indexing
JSONB for Complex Data: Nested health metric check results are stored as JSONB, providing flexibility for evolving data structures without schema changes
Performance Optimization:Critical indexes on timestamp, hub_name, and project_name ensure fast queries even as data grows

Technology Stack Decisions

The technology stack was chosen to balance developer experience, performance, and scalability:

Next.js (App Router): Modern React framework with server-side rendering, API routes, and excellent developer experience
Vercel Postgres: Managed PostgreSQL database with seamless integration, automatic scaling, and built-in connection pooling
Tailwind CSS: Utility-first CSS framework for rapid UI development and consistent design system
TypeScript: Type safety throughout the codebase, reducing bugs and improving maintainability
Chart.js: Powerful charting library for data visualization and analytics

Data Growth & Scalability Strategy

With weekly data tracking, the system is designed to handle significant data accumulation over time:

Pagination: All list endpoints implement pagination (default 50-100 items per page) to handle large datasets
Database Indexing: Strategic indexes on timestamp, hub_name, and project_name ensure query performance as data grows
Composite Indexes: Common query patterns (hub + project, project + timestamp) use composite indexes for optimal performance
Data Retention: All data is kept indefinitely with no automatic cleanup, allowing for long-term trend analysis
Future Optimization: Schema design allows for future partitioning strategies if needed for very large datasets

Key Challenges & Solutions

Challenge: Data Separation
Ensuring clean separation between data storage and presentation logic, allowing for flexible scoring algorithm updates without database migrations.
Solution: Facts-only storage with dynamic scoring calculation in the application layer. Scoring logic is ported from HealthMetric's proven algorithm and can be updated without touching stored data.
Challenge: Scalability
Handling growing data volumes from weekly tracking while maintaining performance through efficient pagination and database indexing.
Solution: Comprehensive indexing strategy, pagination on all list endpoints, and efficient query patterns. The hybrid schema design balances normalized metadata for performance with JSONB for flexibility.
Challenge: Dynamic Scoring
Calculating scores on-the-fly from stored facts rather than pre-computing, enabling algorithm improvements without data migration.
Solution: Scoring algorithm ported to TypeScript, calculated dynamically when data is requested. This allows for algorithm updates, A/B testing, and improvements without any database changes.
Challenge: Cross-Platform Support
Ensuring optimal performance and user experience on both mobile and desktop devices.
Solution: Mobile-first responsive design with Tailwind CSS, touch-friendly interfaces, optimized layouts, and full feature set available on desktop. Responsive breakpoints ensure usability across all device sizes.
Challenge: Performance Optimization
Minimizing wait times and providing seamless user experience from landing page to dashboard.
Solution: Landing page displays aggregated stats for fast initial load, while dashboard data is pre-loaded in the background. This strategy ensures quick initial render and seamless transition to the dashboard.

How It Works

The workflow follows a clean, unidirectional data pipeline designed for reliability and scalability:

Revit Data Extraction: Python scripts (located in revit_extractor/) extract health metric data from Revit models and generate JSON files. The extraction process can be integrated with existing Revit automation tools or run as standalone scripts.
API Ingestion: The extracted JSON data is sent to the /api/data/ingestendpoint using the scripts/send_to_api.pyscript. The API requires authentication via API key and includes strict data validation, rate limiting (100 requests/minute), and a 10 MB payload limit.
Database Storage: Validated data is stored in Vercel Postgres with a hybrid schema design. Core metadata is normalized for efficient querying, while complex nested data is stored as JSONB for flexibility. Only facts are stored - no computed scores.
Dynamic Scoring: When the dashboard requests model data, scores are calculated on-the-fly using the scoring algorithm ported from HealthMetric. This ensures scores always reflect the latest algorithm without requiring data migration.
Dashboard Display: The Next.js dashboard queries data through API endpoints, calculates scores dynamically, and displays results with filtering, sorting, pagination, and chart visualizations. The dashboard is fully responsive and optimized for both mobile and desktop.

Development Approach & Philosophy

Internal Team Focus

EnneadTab BIM Data is designed for internal team use, which influenced several key decisions:

Simplified authentication (API key only, no complex user management)
Professional but optimized for internal use rather than public-facing polish
Development-friendly CORS policy (allows all origins)
Console logging for error tracking (no external error tracking services)

Code Quality & Modularity

The codebase follows strict modularity principles:

Maximum file size guideline (~300-500 lines per file)
One component/functionality per file
Clear, descriptive file names
Pre-commit hooks with Husky and lint-staged for code quality
TypeScript for type safety throughout

Deployment Strategy

Simplified deployment approach for rapid iteration:

Vercel-only deployment (production environment)
No staging/dev environments needed for initial launch
Direct deployment via Git push to main branch
Vercel Pro plan features for production scalability

Testing & Documentation

Pragmatic approach to testing and documentation:

Basic automated tests (unit tests for core functionality)
Manual developer testing for end-to-end workflows
Focus on critical paths and core functionality
Minimal documentation (README.md only) with setup instructions and basic usage

History & Evolution

EnneadTab BIM Data was developed as a modern, scalable solution for Revit project analytics. Built on Next.js and Vercel Postgres, it represents a fresh start with no backward compatibility requirements, allowing the architecture to be optimized for current needs and future extensibility.

The application follows a "facts only" storage approach, storing raw data in the database and calculating scores dynamically. This design decision was critical for long-term maintainability and flexibility. It allows scoring algorithms to be updated, improved, or even A/B tested without requiring database migrations or data reprocessing.

The scoring algorithm was ported from HealthMetric's proven scoring.py, maintaining the same calculation methodology while adapting it to TypeScript for seamless integration with the Next.js application.

Future enhancements planned include chatbot integration for intelligent insights, file attachments support for PDFs and images, advanced analytics features, and potential integration with additional data sources.

Back to Home Go to Dashboard