search

lacuna-tech / mds-core

Repo for LADOT MDS implementation for contribution to the Open Mobility Foundation
Apache License 2.0
13 stars 9 forks source link

[documentation] database schema #624

Open jaimeventura opened 3 years ago

jaimeventura commented 3 years ago

Hello. Im looking at file https://github.com/lacuna-tech/mds-core/blob/develop/packages/mds-db/schema.ts, for analysing the database schema. But, is there any documentation about it? I can do some educated guesses about it. Still it would be great to have de detailed explanation of each table and column.

Thanks.

avatarneil commented 3 years ago

Hi @jaimeventura, thanks for making this issue! Sorry for not getting to this for a couple weeks; too many GitHub notifications 😅

mds-db is currently being phased out in favor of TypeORM managed services (because of the size of this repo and the lack of immediate business value, it has been a rather slow process). The schema definitions found in mds-db there are considered reasonably deprecated, and exist solely so the legacy DB access methods (anything in mds-db) still typecheck. At the moment, most services in this repo are simply using TypeORM for table management (schemas, migrations, etc...) as opposed to using TypeORM for read/write methods; however, some examples of using TypeORM for db access can be found in the mds-geography-service (we're starting to phase them in where we find immediate need).

I absolutely agree that there should be some more documentation around the table schemas, and the hope is that once we've migrated all of the db access methods to the individual services, it will be self-documenting in a sense (usage of the tables will be very clear, and isolated to services which describe them in the README at a high-level). This, in combination with JSDoc comments, ought to satisfy documentation desires! We've historically used TypeDoc for generating documentation straight from the Typescript codebase (it pulls in JSDoc comments for additional context and all that jazz), however that's in a bit of a messy state (at least last I checked, I'll poke around again tonight) due to TypeDoc undergoing extremely breaking changes a couple versions ago (changes which, unfortunately, completely bork our monorepo-wide documentation generation), and the legacy version of TypeDoc doesn't support newer versions of Typescript so it's unusable for this project.

What I imagine you're most interested in, is the schemas which directly relate to the Agency, Policy, and Geography APIs.

While we work on this long lived tech debt cleanup, are there any entities you have specific questions about I could help answer?

avatarneil commented 3 years ago

Some more follow-up on this, I'm investigating getting TypeDoc working again in this project! Seems like support for monorepos was recently added, which is fantastic, however there are some performance issues we're running into given the size of this project. See https://github.com/TypeStrong/typedoc/issues/1606 for details :)

jaimeventura commented 3 years ago

Hey @avatarneil

While we work on this long lived tech debt cleanup, are there any entities you have specific questions about I could help answer? Not really. Im considering starting a project to provide a frontend app do manage the data on the database. As far as i understood, there's so such app where i could for instance, add policies to be available to the providers via MDS API, provide stats over the vehicle usage, ...

Knowing about the spec and looking at the database, i can make educated guesses about this. Still, having a formal document would be nice.

Thanks,

jaimeventura commented 3 years ago

@avatarneil, sorry i mistakenly closed the issue. but im dont know if its worth to keep it open until someone create such document or not. I'll leave the decision to you.