Notion Table View and Filters

A full-stack application implementing Notion table view UI with advanced filtering capabilities, built with React, TypeScript, Node.js, and Docker for easy deployment.

🚀 Quick Start with Docker

Prerequisites:

• Docker and Docker Compose
• Notion API key and Database ID

Setup Steps:

1. Clone and setup environment:

git clone <repository-url>
cd notion-table-view-filters
cp server/.env.example server/.env

2. Add your Notion credentials to server/.env:

NOTION_SECRET=your_notion_integration_token_here
NOTION_DATABASE_ID=your_notion_database_id_here

3. Start the application:

make dev
# Or: docker-compose up --build

4. Access the app:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001

🐳 Docker Commands

# Build and start all services
make dev

# Stop services
make down

# View logs
make logs

# Clean up everything
make clean

# Run tests
make test

📋 Features

Table View UI

• Responsive table display with modern design
• Column sorting functionality
• Drag-and-drop column rearrangement
• Column resizing for optimal viewing
• Loading states and error handling

Advanced Filter System

• Single Filters: Simple filter conditions for individual properties
• Compound Filters: Advanced filtering with logical operators
  • AND/OR Operations: Combine multiple filter conditions
  • NOT Operations: Negate filter conditions with validation
  • Nested Groups: Create complex filter hierarchies (configurable depth)

Property Type Support

• Checkbox (is, is not)
• Date (equals, before, after, between, is empty, is not empty)
• Number (=, ≠, >, <, ≥, ≤, is empty, is not empty)
• Text/Rich Text (is, is not, contains, does not contain, starts with, ends with, is empty, is not empty)
• Select/Multi-select (contains, does not contain, is empty, is not empty)
• Status (is, is not)

NOT Operator Implementation

• Direct Negation: NOT (property = "value") → property != "value"
• Complex Logic: NOT (A AND B) → (NOT A) OR (NOT B)
• Validation System: Real-time error detection for unsupported operators
• User-friendly Messages: Clear error descriptions

Form Validation

• Real-time validation with error messages
• Smart button disabling based on validation state
• Required field validation for all filter inputs
• React Hook Form integration

🛠 Tech Stack

Frontend

• React 19 with TypeScript
• Vite for fast development and building
• Tailwind CSS for utility-first styling
• React Hook Form for form state management
• React DnD Kit for drag-and-drop functionality
• React Testing Library for component testing

Backend

• Node.js with TypeScript
• Express.js REST API
• @notionhq/client for Notion API integration
• CORS enabled for frontend communication

Development Tools

• Docker for containerization
• Docker Compose for multi-service orchestration
• Jest for testing
• ESLint for code linting
• Make for command shortcuts

📁 Project Structure

├── src/                    # Frontend React app
│   ├── components/         # React components
│   │   ├── filters/        # Filter system components
│   │   └── ...             # Other UI components
│   ├── types/              # TypeScript type definitions
│   ├── utils/              # Utility functions
│   └── App.tsx             # Main app component
├── server/                  # Backend Express server
│   ├── src/
│   │   ├── index.ts        # Express server entry point
│   │   └── types/          # Backend type definitions
│   ├── Dockerfile          # Backend Docker configuration
│   ├── .env.example        # Environment variables template
│   └── package.json        # Backend dependencies
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile              # Frontend Docker configuration
├── Makefile                # Command shortcuts
└── README.md               # This file

🔧 Configuration

Environment Variables

Create server/.env based on server/.env.example:

# Required: Get from https://www.notion.so/my-integrations
NOTION_SECRET=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id

# Optional
PORT=3001
HOST=0.0.0.0
NODE_ENV=production

Getting Notion API Credentials

1. Create Integration:

   • Go to https://www.notion.so/my-integrations
   • Click "New integration"
   • Give it a name and select your workspace
   • Copy the "Internal Integration Token"

2. Share Database:

   • Open your Notion database
   • Click "..." → "Connections"
   • Add your integration

3. Get Database ID:

   • Open your Notion database
   • Copy the ID from the URL (the part after notion.so/ and before ?v=)

🧪 Testing

Running Tests

# Frontend tests
npm test

# Backend tests (if available)
cd server && npm test

# Test with Docker
make test

Test Coverage

• Unit Tests: Core utility functions for NOT operator validation
• Component Tests: Filter components with React Testing Library
• Integration Tests: Form validation and user interactions

🚀 Deployment

Docker Deployment (Recommended)

# Production deployment
make deploy

# Or manually:
docker-compose -f docker-compose.yml up --build -d

Alternative Deployments

Frontend Only

• Vercel: vercel --prod
• Netlify: Drag dist folder to netlify.com/drop
• GitHub Pages: npm run deploy

Backend Only

• Railway: railway up
• Render: Connect GitHub repo
• Heroku: Git push to Heroku

🎯 Advanced Features

Filter Processing

Filter Flattening

• Handles filters with more than 2 nesting levels
• Converts deeply nested structures into manageable forms
• Configurable depth (default: 2 levels)

Filter Splitting

• Splits complex filters into multiple simpler groups
• Prevents Notion API limit violations
• Chunked processing (default: 10 filters per group)

Filter Optimization

• Combines flattening and splitting based on complexity
• Smart algorithms for optimal processing
• Configurable options for customization

Performance Optimizations

• Container health checks for reliability
• Non-root Docker users for security
• Optimized Docker layers for faster builds
• CORS configuration for seamless frontend-backend communication

🔍 API Endpoints

Backend Server (Port 3001)

• GET /structure - Get database structure and properties
• POST /query - Query database with filters and sorting
• OPTIONS / - CORS preflight handling

Request Examples

// Get database structure
GET http://localhost:3001/structure

// Query with filters
POST http://localhost:3001/query
{
  "filter": {
    "and": [
      {
        "property": "Status",
        "select": {
          "equals": "Done"
        }
      }
    ]
  },
  "sorts": [
    {
      "property": "Created",
      "direction": "descending"
    }
  ],
  "page_size": 50
}

🐛 Troubleshooting

Common Issues

1. "Must define NOTION_SECRET and NOTION_DATABASE_ID"

   • Ensure you created server/.env from server/.env.example
   • Check that your Notion integration has access to the database

2. Frontend can't reach backend

   • Ensure both containers are running: docker-compose ps
   • Check logs: make logs

3. Build errors

   • Clean and rebuild: make clean && make dev
   • Check Node.js version compatibility

Docker Issues

# Check container status
docker-compose ps

# View logs
docker-compose logs [service-name]

# Restart services
docker-compose restart

# Clean everything
make clean

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

ISC

🙏 Notes for Reviewers

Key Implementation Highlights

• Full Docker Integration: Complete containerization with health checks and security best practices
• Advanced NOT Operator: Complex negation logic with comprehensive validation
• Filter Optimization: Automatic flattening and splitting for large queries
• Type Safety: Full TypeScript coverage across frontend and backend
• Testing: Comprehensive test suite with Jest and React Testing Library
• Production Ready: Environment variable management, error handling, and deployment configurations

Technical Decisions

• Used React Hook Form for superior form state management
• Implemented custom filter flattening to handle Notion API limitations
• Added Makefile for simplified Docker operations
• Structured monorepo-style with separate frontend and backend
• Implemented non-root Docker users for security

Performance Considerations

• Docker layer optimization for faster builds
• Filter chunking to prevent API timeouts
• Lazy loading and code splitting opportunities
• Health checks for service reliability

This application demonstrates advanced React development, API integration, and production deployment practices.