How mbsantiago/whombat works
Project Type and Purpose
• Whombat is a full-stack application with a clear separation between the backend (Python-based) and the frontend (Next.js/React). The tool is built to help users label audio data for machine learning research, with special emphasis on bioacoustics.
• The README confirms its usage as a stand-alone bundled executable as well as a Python package, and the detailed developer and user guides imply a mature, multi-component system.
Analyzing the File Structure
• The project is split into major directories:
• “back”: This is the backend component written in Python. It contains directories for API routes, core business logic (the “system” and “core” folders), models, migrations (using Alembic), schemas, and utilities. It is clearly organized in a modular way, likely following an MVC-like or service-oriented architecture.
• “front”: This contains a Next.js/React frontend application. It is organized with pages, components, hooks, and library utilities, which support the web interface and communication with backend APIs.
• Other top-level files include CI/CD configurations (.github/workflows), Dockerfiles (both at the root and within “back” and “front”), environment configuration files, and various scripts for bundling, development, and tests.
• Configuration and deployment files (like Dockerfiles, compose files, and GitHub Actions) indicate that the project is designed to be containerized and continuously integrated/deployed.
Main Architectural Components
a. Frontend Component:
• A Next.js/React-based client application.
• Organized with pages, contexts, and components that handle views (like authentication pages, annotation projects, dataset views, evaluation, exploration, and settings).
• Utilizes various custom hooks and libraries to handle API calls, state management, and real-time interactions (e.g., canvas interactions for annotating audio).
b. Backend Component:
• A Python-based API server which likely uses FastAPI (or a similar framework) as indicated by files such as app.py, system routes, and middleware.
• Contains the API layer, with well-separated routes, controllers, and dependency injection (see the “routes/dependencies” directory).
• Incorporates business logic (in “core” and “system” folders), data I/O (in “api/io” folders for managing annotation projects, datasets, etc.), and error handling/middleware.
c. Database and Persistence:
• Although no specific database platform is mentioned, the presence of migrations (using Alembic, detailed in “migrations” directories) strongly suggests integration with a relational database.
• The “models” and “schemas” directories represent the ORM layer and API data contracts.
d. Supporting Components and External Services:
• Docker and container orchestration support (the Dockerfiles and Compose files indicate separate containerized deployments for development and production).
• CI/CD tools (GitHub workflows for building, testing, publishing, and documentation).
• Integration with user authentication (see “routes/auth” and “system/auth.py”) and possibly external storage for audio files (inferred from the “audio” directories and sample audio data).
Interactions and Data Flow
• The backend processes requests, interacts with the database (through ORM/migrations), and returns responses to the frontend.
• Containerization and automation (Docker and CI/CD tools) are supporting the deployment pipeline. They can be shown as an overlay or as external components that manage builds and deployments.
• Representing user interactions (via the web interface) and API flows (data retrieval, annotation submission, and annotation updates).
Architectural Patterns and Design Principles
• Separation of Concerns: The system is cleanly divided between frontend (presentation and client-side logic), backend (API and business logic), and persistence (database and ORM).
• Modularity: The backend modules (API, core, filters, migrations, models, schemas) and the rich frontend components (organized by functionality such as annotation projects, datasets, audio handling, etc.) demonstrate a modular design.
• Use of Containerization and CI/CD: Dockerfiles and GitHub workflows indicate a modern, automated approach to development and production deployments.
• Clear interaction design between UI elements, API endpoints, and data layers.