Repository navigation
Add architecture and contributor documentation - #758
Merged
glenflorendo merged 1 commit intoSep 15, 2026
Merged
Conversation
The repository spans a Next.js app, an Express API, two Python data pipelines, and three databases, with no single place explaining how they relate or which parts are actually wired together. New contributors had to infer that from source. Add eight topic documents under docs/, linked from a new "Detailed documentation" section in docs/README.md: - 01-overview: mission and high-level architecture - 02-monorepo-structure: workspace layout, tooling, local dev - 03-web-application: Next.js map app, state, Socrata integration - 04-backend-api: Express/MongoDB API and its contract - 05-data-pipeline: Polars + SQLite/PostGIS ingestion and schemas - 06-legacy-data-science: older ETL and normalized PostGIS schema - 07-data-sources-and-schemas: dataset IDs and column dictionary - 08-roadmap-and-open-questions: known gaps and open decisions The docs are explicit about what is aspirational versus working - the web app does not currently call the Express API, for instance - so the diagrams are not mistaken for the intended end state. Note: 05-data-pipeline.md and docs/README.md link to data-science/beta_pipeline/, so this should merge after the pipeline work or those three links will 404. Co-authored-by: Cursor <cursoragent@cursor.com>
|
@gregpawin, this Pull Request is not linked to a valid issue. Please provide a valid linked issue in "Related Issues" above, using the format of "Resolves #" + issue number. |
glenflorendo
self-requested a review
September 15, 2026 18:22
glenflorendo
approved these changes
Sep 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds eight topic documents under
docs/, linked from a new "Detailed documentation" section indocs/README.md.The repository spans a Next.js app, an Express API, two Python data pipelines, and three databases, and there was no
single place explaining how those relate or which parts are actually wired together. New contributors had to infer it
from source.
01-overview.md02-monorepo-structure.md03-web-application.md04-backend-api.md05-data-pipeline.md06-legacy-data-science.md07-data-sources-and-schemas.md08-roadmap-and-open-questions.mdThe docs distinguish what works from what is aspirational — that the web app does not currently call the Express API, for
instance — so the diagrams are not misread as the intended end state. Anywhere behavior was unclear from source, it is
recorded as an open question in
08rather than guessed at.The change to
docs/README.mdis purely additive: it appends a section and touches nothing upstream already had.Related Issues
Refs #695
This PR has no dedicated issue and does not implement any of #695's acceptance criteria — it documents the pipeline
work referenced there, which is why it is linked at all. Since the PR template requires an approved issue, tell me
whether you would like me to open a documentation issue for this, or whether you would rather fold these docs into the
wiki instead of the repo. Happy to close this if documentation lives elsewhere by convention.
Testing
Not applicable — documentation only, no executable code.
Verified every relative link resolves. Three of them (
05-data-pipeline.mdanddocs/README.mdpointing intodata-science/beta_pipeline/) depend on the pipeline PR, so this should merge after that one or those links will404. Confirmed the mermaid diagrams render on GitHub.
Checklist
changes or issues.
Last box unchecked: this is documentation and does not satisfy #695's criteria, which are about ingestion behavior.