dataesr/paysage-api

1. This repository is a Node.js backend API for “Paysage”, centered on managing a large catalog of public-organization data: structures, persons, projects, terms, categories, relations, documents, and related metadata. The README and folder layout suggest an Express-style HTTP service exposed as a REST API with OpenAPI documentation.

2. The application entry points are split between index.js, src/api/app.js, and src/api/index.js. src/config.js and the src/setup/* modules indicate bootstrapping for external infrastructure before the API starts, especially MongoDB, Elasticsearch, and storage.

3. The HTTP layer is organized by domain under src/api/*. Each major business object has its own route bundle, for example structures, persons, projects, terms, categories, relations, groups, documents, domains, officialtexts, prizes, legalcategories, email-types, followups, journal, search, auth, users, apikeys, and me. This is the primary boundary for the architecture diagram.

4. Most domains have nested subresources that reflect the data model rather than generic CRUD only. Examples include identifiers, web links, social media, localisations, emails, names, logos, key numbers, geographical categories, and group members. That implies a hierarchical resource model with many child collections attached to a root entity.

5. Cross-cutting behavior is centralized in src/api/commons/middlewares. These middlewares cover authentication, RBAC, validation, file handling, event handling, CRUD orchestration, alternative IDs, context propagation, and error handling. In the architecture, these sit between route definitions and the service/repository layer.

6. Persistence is MongoDB-first. src/services/mongo.service.js, src/setup/mongo.js, and the repository helpers under src/api/commons/libs show a repository abstraction over Mongo collections, including base and nested repositories. This suggests most API operations read/write Mongo documents directly through a shared data-access layer.

7. Elasticsearch is a second major data store, but mainly for search and indexing rather than as the source of truth. The search routes, the various *.elastic.js query files, and src/services/elastic.service.js indicate a dedicated search/indexing path for autocomplete and aggregated lookup queries across entities such as structures, persons, projects, legal categories, and terms.

8. File and media handling are handled separately from core entity data. src/services/storage.service.js, src/api/assets, src/api/files, and the OpenAPI file schemas indicate that documents or binaries are stored outside MongoDB, while the API manages metadata and access to those files.

9. Authentication and authorization are explicit subsystems. src/api/auth, src/api/apikeys, src/api/users, and src/api/me point to sign-in/sign-out/token flows, API key management, and user profile access. These are backed by queries for user/admin/token views and enforced through auth/RBAC middlewares.

10. Background processing is substantial and part of the architecture, not a side detail. src/jobs contains indexing, email validation, Sirene synchronization, open-data imports, dump generation, key-number datasets, treatments, and notifications. These jobs likely act on MongoDB data, update Elasticsearch indexes, and call external services such as mail or Mattermost.

11. The scripts/ directory contains operational import/reset utilities, especially for geographical categories and localisation status. Together with mongo-init.js, this indicates bootstrap and data-seeding workflows for local or fresh environments.

12. The repo is designed with strong API contract discipline. src/openapi contains the full API specification, path definitions, schemas, parameters, and error responses, while docs/ provides human documentation. This makes the OpenAPI model a key architectural artifact alongside the code.

13. Tests are organized by domain and also cover shared infrastructure. There are unit/integration tests for categories, persons, projects, structures, legal categories, document types, official texts, search, and base repository behavior, plus dedicated test setup under tests/. GitHub Actions and Docker Compose files show the project is built and tested in containerized CI environments.

14. In diagram terms, the main flow is: client request -> route module -> shared middlewares -> domain logic/repository -> MongoDB and/or Elasticsearch -> optional storage/mail/external integrations -> response. Jobs and scripts operate alongside this path as asynchronous or operational pipelines over the same underlying data stores.