How aa-whaledev/acartia works
Project type and purpose
• This is a full-stack web application (“Acartia”) that acts as a decentralized data cooperative for sharing marine animal location data in real time.
• Frontend: Vue.js single-page app.
• Backend: Node.js/Express REST API.
• Persistence: MongoDB (via Mongoose) for user accounts, sightings, password resets; OrbitDB for decentralized, peer-to-peer data replication.
• Authentication & Authorization: JWT, Passport.
• Auxiliary services: SendGrid for email, integration with partner APIs (Citizen Science API, ORCA map, Spotter API).
File structure
• Top-level: configuration files (.babelrc, .env.example, Dockerfile, CI/CD workflows).
• src/api: Express controllers, routes and models organized per feature (auth, data-ingestion, partner-data, password-reset, user).
• src/services: wrappers around core services (express app, JWT, Mongoose, OrbitDB, Passport, response formatting, SendGrid).
• src/client: Vue project with components, pages, assets, build configs.
• src/public: static assets (CSV templates).
• test & src/*/*.test.js: unit and integration tests.
• build_and_deploy.sh & GitHub Actions (.github/workflows) & Travis: CI/CD pipelines, Docker orchestration.
Readme insights
• Phased roadmap (prototype, feature expansion, transboundary integration).
• API endpoints documented under /api/v1/sightings.
• OrbitDB used for decentralized document store.
• Encourages open contribution & web3 demonstration.
Main components & their interactions
a. Frontend (Vue.js SPA)
• Runs in browser, served by webpack dev server or static build.
• Presents pages (Login, Register, Dashboard, Maps, Heatmaps, etc.).
• Calls backend REST API (/api/v1/*) over HTTP/HTTPS, attaches JWT tokens.
b. Backend API (Express)
• Entrypoint: src/index.js and src/app.js.
• Routes in src/api/** dispatch to controllers.
• Controllers orchestrate service calls, model operations.
c. Service layer (src/services)
• express: central app instance, middleware registration.
• mongoose: connects to MongoDB, defines schemas (User, Token, PasswordReset, Sighting).
• orbitdb: initializes peer-to-peer store for decentralized sightings replication.
• jwt & passport: handle auth strategies, token issuance and validation.
• sendgrid: sends emails (registration confirmations, password resets).
• response: standardizes API responses.
d. Datastores & external systems
• MongoDB: primary persistence for users, trusted sightings, tokens.
• OrbitDB Network: CRDT-based replication across peers.
• Partner APIs: Citizen Science, ORCA Map, Spotter—pulled via HTTP clients.
e. CI/CD & Deployment
• build_and_deploy.sh: build Docker images, run migrations, deploy.
• .github/workflows/deploy-service.yml & .travis.yml: automated testing, building, deploying.
Architectural patterns & design principles
• Layered architecture (Presentation → API → Services → Data).
• MVC-style separation in Express (routes/controllers/models).
• Adapter pattern for external partner APIs & services wrappers.
• Micro-layers: each service in src/services encapsulates third-party integration.
• Eventual consistency via OrbitDB for decentralized data sync.