How howsair/server works
Project type and purpose
• This is a backend‐only application named “HowsAir Server.” Its primary role is to provide a RESTful API for storing, querying, and visualizing environmental measurement data.
• Key technologies: Node.js, Express, TypeScript, PostgreSQL (via Prisma ORM), cron jobs for scheduled map generation, external services (Cloudinary, email), Docker/Docker Compose for containerization, and Vitest for tests.
File structure
• Top-level folders and files
– src/ – application code (app.ts, controllers, routes, services, middleware, cron jobs, utilities, types)
– prisma/ – database schema, migrations, seed script
– docs/ – auto-generated API and code documentation
– test/ – unit tests organized by feature area
– Dockerfile, docker-compose.yml – containerization setup
– .github/workflows/ci.yml – CI pipeline for building, testing, linting
• Architectural patterns
– Layered MVC-style separation: routes → controllers → services → Prisma client (data layer)
– Middleware pipeline for authentication, error handling
– Scheduled tasks module (src/cron/jobs) that runs on a schedule to generate air quality maps and push to Cloudinary
– Utility modules for cross-cutting concerns (authUtils, emailSenderUtils, map generation, validators)
README for additional insights
• Describes local development workflow (npm run setup spins up PostgreSQL, seeds data, Prisma Studio)
• CI uses Vitest for unit tests
• Production uses Docker Compose to stand up backend and database containers, optional HTTPS via self-signed certs, and static compilation of a separate frontend client.
• External integrations: Cloudinary for image storage, email provider for verification/reset, SonarQube for code quality.