# aa-whaledev/acartia architecture

> Architecture diagram of the GitHub repository aa-whaledev/acartia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aa-whaledev/acartia
- Repository: https://github.com/aa-whaledev/acartia

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Client["Browser / Vue.js SPA"]:::frontend
        MainJS["src/client/src/main.js"]:::frontend
        Pages["src/client/src/components/Pages/"]:::frontend
        Components["src/client/src/components/"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        direction TB
        APIEntry["src/index.js / src/app.js"]:::backend
        Routes["src/api/index.js"]:::backend

        subgraph "API Features"
            direction TB
            AuthIndex["src/api/auth/index.js"]:::backend
            AuthCtrl["src/api/auth/controller.js"]:::backend

            UserIndex["src/api/user/index.js"]:::backend
            UserCtrl["src/api/user/controller.js"]:::backend
            UserModel["src/api/user/model.js"]:::backend
            UserToken["src/api/user/token.model.js"]:::backend

            PWResetIndex["src/api/password-reset/index.js"]:::backend
            PWResetCtrl["src/api/password-reset/controller.js"]:::backend
            PWResetModel["src/api/password-reset/model.js"]:::backend

            DataIngestIndex["src/api/data-ingestion/index.js"]:::backend
            DataIngestCtrl["src/api/data-ingestion/controller.js"]:::backend

            subgraph "Partner Data Adapters"
                direction TB
                CSAPI["src/api/partner-data/citizen-science-api.js"]:::backend
                ORCAAPI["src/api/partner-data/orca-map-api.js"]:::backend
                SpotterAPI["src/api/partner-data/spotter-api.js"]:::backend
                PDUtils["src/api/partner-data/utils.js"]:::backend
            end
        end
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ExpressS["src/services/express/index.js"]:::service
        JWTService["src/services/jwt/index.js"]:::service
        PassportService["src/services/passport/index.js"]:::service
        MongooseS["src/services/mongoose/index.js"]:::service
        OrbitDBS["src/services/orbitdb/index.js"]:::service
        SendGridS["src/services/sendgrid/index.js"]:::service
        ResponseS["src/services/response/index.js"]:::service
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        MongoDB["MongoDB (via Mongoose)"]:::datastore
        OrbitDBNet["OrbitDB Network (IPFS)"]:::datastore
        CSVTemplate["src/public/acartia-import-template.csv"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PartnerCS["Citizen Science API"]:::external
        PartnerORCA["ORCA Map API"]:::external
        PartnerSpotter["Spotter API"]:::external
        SendGridAPI["SendGrid Email"]:::external
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        BuildScript["build_and_deploy.sh"]:::devops
        GHWorkflow[".github/workflows/deploy-service.yml"]:::devops
        TravisCI[".travis.yml"]:::devops
        DockerCfg["Dockerfile / .dockerignore"]:::devops
        EnvConfig[".env.example / src/config.js"]:::devops
    end

    %% Connections
    Client -->|HTTP + JWT| APIEntry
    MainJS --> Client
    Pages --> Client
    Components --> Client

    APIEntry --> Routes
    Routes --> AuthIndex
    Routes --> UserIndex
    Routes --> PWResetIndex
    Routes --> DataIngestIndex
    Routes --> CSAPI
    Routes --> ORCAAPI
    Routes --> SpotterAPI

    AuthIndex --> AuthCtrl
    UserIndex --> UserCtrl
    UserCtrl --> UserModel
    UserCtrl --> UserToken
    PWResetIndex --> PWResetCtrl
    PWResetCtrl --> PWResetModel
    DataIngestIndex --> DataIngestCtrl

    AuthCtrl -->|uses| JWTService
    AuthCtrl -->|uses| PassportService
    UserCtrl -->|uses| MongooseS
    PWResetCtrl -->|uses| SendGridS
    DataIngestCtrl -->|uses| OrbitDBS
    CSAPI -->|adapter| ExpressS
    ORCAAPI -->|adapter| ExpressS
    SpotterAPI -->|adapter| ExpressS

    ExpressS --> MongoDB
    MongooseS --> MongoDB
    OrbitDBS ---|P2P sync| OrbitDBNet
    SendGridS --> SendGridAPI
    ResponseS --> Routes

    CSAPI --> PartnerCS
    ORCAAPI --> PartnerORCA
    SpotterAPI --> PartnerSpotter

    BuildScript --> GHWorkflow
    BuildScript --> TravisCI
    BuildScript --> DockerCfg
    GHWorkflow --> DockerCfg
    TravisCI --> DockerCfg
    DockerCfg --> EnvConfig

    %% Click Events
    click MainJS "https://github.com/aa-whaledev/acartia/blob/main/src/client/src/main.js"
    click Pages "https://github.com/aa-whaledev/acartia/tree/main/src/client/src/components/Pages/"
    click Components "https://github.com/aa-whaledev/acartia/tree/main/src/client/src/components/"
    click APIEntry "https://github.com/aa-whaledev/acartia/blob/main/src/index.js"
    click APIEntry "https://github.com/aa-whaledev/acartia/blob/main/src/app.js"
    click Routes "https://github.com/aa-whaledev/acartia/blob/main/src/api/index.js"
    click AuthIndex "https://github.com/aa-whaledev/acartia/blob/main/src/api/auth/index.js"
    click AuthCtrl "https://github.com/aa-whaledev/acartia/blob/main/src/api/auth/controller.js"
    click UserIndex "https://github.com/aa-whaledev/acartia/blob/main/src/api/user/index.js"
    click UserCtrl "https://github.com/aa-whaledev/acartia/blob/main/src/api/user/controller.js"
    click UserModel "https://github.com/aa-whaledev/acartia/blob/main/src/api/user/model.js"
    click UserToken "https://github.com/aa-whaledev/acartia/blob/main/src/api/user/token.model.js"
    click PWResetIndex "https://github.com/aa-whaledev/acartia/blob/main/src/api/password-reset/index.js"
    click PWResetCtrl "https://github.com/aa-whaledev/acartia/blob/main/src/api/password-reset/controller.js"
    click PWResetModel "https://github.com/aa-whaledev/acartia/blob/main/src/api/password-reset/model.js"
    click DataIngestIndex "https://github.com/aa-whaledev/acartia/blob/main/src/api/data-ingestion/index.js"
    click DataIngestCtrl "https://github.com/aa-whaledev/acartia/blob/main/src/api/data-ingestion/controller.js"
    click CSAPI "https://github.com/aa-whaledev/acartia/blob/main/src/api/partner-data/citizen-science-api.js"
    click ORCAAPI "https://github.com/aa-whaledev/acartia/blob/main/src/api/partner-data/orca-map-api.js"
    click SpotterAPI "https://github.com/aa-whaledev/acartia/blob/main/src/api/partner-data/spotter-api.js"
    click PDUtils "https://github.com/aa-whaledev/acartia/blob/main/src/api/partner-data/utils.js"
    click ExpressS "https://github.com/aa-whaledev/acartia/blob/main/src/services/express/index.js"
    click JWTService "https://github.com/aa-whaledev/acartia/blob/main/src/services/jwt/index.js"
    click PassportService "https://github.com/aa-whaledev/acartia/blob/main/src/services/passport/index.js"
    click MongooseS "https://github.com/aa-whaledev/acartia/blob/main/src/services/mongoose/index.js"
    click OrbitDBS "https://github.com/aa-whaledev/acartia/blob/main/src/services/orbitdb/index.js"
    click SendGridS "https://github.com/aa-whaledev/acartia/blob/main/src/services/sendgrid/index.js"
    click ResponseS "https://github.com/aa-whaledev/acartia/blob/main/src/services/response/index.js"
    click CSVTemplate "https://github.com/aa-whaledev/acartia/blob/main/src/public/acartia-import-template.csv"
    click BuildScript "https://github.com/aa-whaledev/acartia/blob/main/build_and_deploy.sh"
    click GHWorkflow "https://github.com/aa-whaledev/acartia/blob/main/.github/workflows/deploy-service.yml"
    click TravisCI "https://github.com/aa-whaledev/acartia/blob/main/.travis.yml"
    click DockerCfg "https://github.com/aa-whaledev/acartia/tree/main/Dockerfile"
    click EnvConfig "https://github.com/aa-whaledev/acartia/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#28A745,color:#28A745;
    classDef service fill:#FFF5CC,stroke:#FFDD44,color:#995C00;
    classDef datastore fill:#FFE8D6,stroke:#F45B69,color:#A10D2C;
    classDef external fill:#F0E6FF,stroke:#8A2BE2,color:#5D3FD3;
    classDef devops fill:#E8E8E8,stroke:#6A737D,color:#24292E;
```
