enose-core

Repository for the enose-core project — the core system for piezosensor data processing and analysis.

Tech Stack

• Backend: Go 1.23+ (Gin, GORM, golang-migrate)
• Frontend: React 19 (Vite, TypeScript, Tailwind CSS)
• ML: Python 3.12+ (managed via uv)
• Database: PostgreSQL 15+
• Automation: Taskfile, pre-commit hooks
• API Documentation: Swagger (auto-generated via swaggo)

---

Quick Start with Docker

1. Prerequisites

• Docker Compose v2.0+
• Task (optional, for convenient commands)

2. Setup

Copy environment files and configure as needed:

cp .env.docker.example .env.docker
cp apps/backend/.env.example apps/backend/.env

3. Run

Start all services (backend, frontend, postgres, pgadmin, migrations):

task dev:run

Or directly:

docker compose up --build

Services will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger/index.html
• pgAdmin: http://localhost:5050
• PostgreSQL: localhost:5432

---

Local Development (without Docker)

1. System Requirements

Install the following on your local machine:

• Go 1.23+
• Node.js v20+ and npm
• Python 3.12+ with uv
• Task
• PostgreSQL 15+

2. Clone and Setup

git clone git@github.com:CreoCot/enose-core.git
cd enose-core

# Install dependencies and pre-commit hooks
task setup

3. Backend Configuration

Copy and configure environment variables:

cp apps/backend/.env.example apps/backend/.env

Edit apps/backend/.env with your local PostgreSQL credentials.

Start a local PostgreSQL instance (or use existing):

docker run --name enose-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=enose -p 5432:5432 -d postgres:15

Apply database migrations:

task backend:db:init

Start the backend:

task backend:run

4. Frontend

task frontend:run

---

API Documentation

The backend automatically generates Swagger documentation from code annotations.

Access Swagger UI: http://localhost:8080/swagger/index.html

Regenerate documentation (after adding new endpoints):

cd apps/backend
swag init -g cmd/api/main.go -o docs/swagger

---

Database Migrations

Migrations are managed via golang-migrate and stored in apps/backend/database/migrations/.

Apply pending migrations:

task backend:db:init

Rollback all migrations (destructive):

task backend:db:down

Check current migration version:

task backend:db:status

Create a new migration:

cd apps/backend
migrate create -ext sql -dir database/migrations -seq your_migration_name

---

Testing

Backend

Check backend health endpoint:

curl http://localhost:8080/api/v1/health | jq

Expected response:

{
  "status": "OK",
  "timestamp": "Sun, 14 Jun 2026 16:25:56 UTC",
  "version": "1.0.0-mvp",
  "uptime": "55.332075718s",
  "database": "ok"
}

Check table generation endpoint:

curl http://localhost:8080/api/v1/table | jq

Run backend unit tests:

cd apps/backend
go test ./... -v

Frontend

Visit http://localhost:5173 and verify the application loads correctly.

Run frontend tests (if configured):

cd apps/frontend
npm test

Database

Verify migrations were applied:

docker exec -i enose-postgres psql -U postgres -d enose -c '\dt'

Or connect via pgAdmin at http://localhost:5050:

• Host: postgres (inside Docker network) or localhost (from host)
• Port: 5432
• Username: postgres
• Password: postgres

---

Git Workflow

Direct pushes to dev and main branches are blocked. All changes must go through Pull Requests.

Branches

• dev — main development branch (default). All features merge here.
• main — release branch. Updated infrequently.

Creating a Feature Branch

Always create branches from the latest dev:

git checkout dev
git pull
git checkout -b <type>/<task-name>

Branch types (lowercase, with slash):

• feature/ — new features (e.g., feature/login-page)
• bugfix/ — bug fixes in dev environment (e.g., bugfix/api-cors)
• refactor/ — code refactoring and optimization (e.g., refactor/auth-middleware)

Commits

Use Conventional Commits format. The linter will reject incorrectly named commits. Write in English, keep it concise:

• feat: add email login support
• fix: resolve crash on null response
• refactor: simplify auth middleware

Pull Request Process

1. Push your local branch: git push origin feature/my-feature
2. Open a PR on GitHub. Target branch defaults to dev.
3. Requires at least 1 approval from a Code Owner.
4. Merge via Squash and Merge (all your commits will be squashed into one in dev).

Hotfixes

If a critical bug appears on production (main) while dev is unstable:

1. Create branch from main: git checkout main && git checkout -b hotfix/critical-bug
2. Fix the bug and open two PRs: one to main (to fix production), one to dev (to preserve the fix for the next release).

---

Core Project Structure

enose-core/
├── apps/
│   ├── backend/          # Go API server
│   │   ├── cmd/
│   │   │   ├── api/      # Main API entry point
│   │   │   └── migrate/  # Migration CLI tool
│   │   ├── internal/
│   │   │   ├── config/   # Configuration management
│   │   │   ├── database/ # Database connection and migrations
│   │   │   ├── handlers/ # HTTP handlers
│   │   │   ├── middleware/ # Gin middleware
│   │   │   └── server/   # Router setup
│   │   ├── database/
│   │   │   └── migrations/ # SQL migration files
│   │   └── docs/
│   │       └── swagger/  # Auto-generated Swagger docs
│   ├── frontend/         # React application
│   └── ml/               # Python ML service
├── docker-compose.yml    # Docker orchestration
├── Taskfile.yml          # Task automation
└── README.md

---

Troubleshooting

Port already in use

If port 8080 or 5173 is occupied, stop the conflicting service or change the port in .env files.

Database connection failed

Ensure PostgreSQL is running and credentials in apps/backend/.env are correct. Check with:

docker exec -i enose-postgres psql -U postgres -d enose -c "SELECT 1"

Swagger documentation not loading

Regenerate the docs:

cd apps/backend
swag init -g cmd/api/main.go -o docs/swagger

Then restart the backend.