Wellysa API

Modern TypeScript API service built with Hono framework, featuring OpenAPI documentation, NocoDB integration, and MongoDB storage.

Tech Stack

• Runtime: Node.js with Bun/npm package management
• Framework: Hono 4.6 — ultra-fast web framework
• Language: TypeScript 5.7
• Validation: Zod with OpenAPI schema generation
• Database: MongoDB 6.19 + NocoDB SDK 0.258
• Documentation: Scalar API Reference (auto-generated from OpenAPI)
• Logging: tslog 4.9
• Build Tools: tsup (bundler), tsx (dev runner)
• Code Quality: ESLint, Prettier, Husky, Commitlint

Prerequisites

• Node.js 18+ (or Bun runtime)
• MongoDB instance (local or remote)
• NocoDB instance (for admin/data management)

Installation

# Clone repository
git clone <repository-url>
cd api

# Install dependencies
npm install
# or
bun install

# Configure environment
cp .env.example .env  # (unverified — create if missing)
# Set required variables: MONGODB_URI, NOCODB_API_TOKEN, etc.

Development

# Start development server (hot reload)
npm run dev

# Format code
npm run format

# Build for production
npm run build

# Start production server
npm start

Server runs on http://localhost:3000 (default — confirm with team if different).

Scripts Reference

Core Development

• npm run dev — Start development server with hot reload (tsx watch)
• npm run build — Build production bundle with tsup
• npm start — Run production server from dist/

Data Synchronization

• npm run sync:deploy — Deploy-safe sync (NocoDB → MongoDB, skip if already synced)
• npm run sync:noco-to-mongo — Full sync from NocoDB to MongoDB
• npm run verify:sync — Verify NocoDB/MongoDB data consistency
• npm run mongo:dev — Dry-run sync (preview changes without applying)

Code Quality

• npm run format — Format codebase with Prettier
• npm run check-lock-files — Validate lock file integrity
• npm test — Run test suite (currently placeholder)

Debug/Analysis Scripts

Additional utilities in scripts/ directory:

• compare-v2-v3.ts — Compare v2/v3 implementations
• debug-pct-*.ts — Debug percentage calculations (unverified domain context)
• diagnose-*.ts — Diagnostic tools for data integrity
• verify-*.ts — Verification scripts for algorithm correctness

Architecture Overview

src/
├── __internals/        # Framework abstractions & routing DSL
│   ├── builders/       # AppBuilder, EndpointHandlerBuilder
│   ├── core/           # Route combinators, endpoint primitives
│   └── interfaces/     # TypeScript interfaces for framework
│
├── infra/              # Infrastructure concerns
│   ├── cache/          # Caching layer (implementation TBD)
│   └── logger/         # tslog adapter & configuration
│
├── lib/                # Shared utilities
│   ├── constants/      # App-wide constants & regex patterns
│   ├── exceptions/     # HTTP exception classes
│   ├── middleware/     # Request/response middleware
│   └── db-data-table-row.client.ts  # DB abstraction client
│
├── modules/
│   └── engine/         # Core business logic module
│       ├── core/       # Engine domain logic
│       ├── helpers/    # Utility functions
│       ├── integrations/  # Data sources (in-memory, NocoDB)
│       ├── loaders/    # Data loading strategies
│       ├── parsers/    # Input parsing
│       ├── schemas/    # Zod validation schemas
│       ├── transformers/  # Data transformation pipelines
│       └── v2/         # Version 2 implementation (parallel track)
│
├── routes/             # API route definitions
├── node/               # Node.js-specific utilities
└── server.ts           # Application entry point

API Documentation

Interactive API documentation available at /reference (Scalar UI) when server is running.

OpenAPI schema auto-generated from Zod schemas using @hono/zod-openapi.

Key Endpoints

(unverified — confirm with team)

• GET /health — Health check
• POST /api/engine/* — Engine computation endpoints (TBD)
• Additional routes defined in src/routes/

Data Flow

1. NocoDB serves as admin interface and primary data source
2. Synchronization scripts migrate data to MongoDB (run via sync:deploy on deployment)
3. MongoDB acts as production database for API queries
4. Verification scripts ensure data consistency between sources

Deployment

# Pre-deployment sync
npm run sync:deploy

# Build production assets
npm run build

# Start server
npm start

Environment Variables (unverified — create .env with):

MONGODB_URI=mongodb://...
NOCODB_API_TOKEN=...
NOCODB_BASE_URL=...
PORT=3000
NODE_ENV=production

Git Workflow

• Commits: Conventional Commits enforced via Commitlint
• Pre-commit hooks: Husky runs format checks before commit
• Lock files: Automated check prevents conflicting package-lock.json/bun.lockb

Development Notes

• Version migration in progress: Codebase contains both v2 and v3 implementations (see scripts/compare-v2-v3.ts)
• Engine module: Core business logic under active development (confirm domain context with team)
• Test suite: Currently minimal — expansion recommended

Status

Active Development — API functional, v2→v3 migration in progress. Production-ready for existing endpoints; new features under development.

---

Maintained by: Wellysa Team
Questions?: Contact repository maintainers or check inline code documentation