How carrismetropolitana/api works
Project Type and Purpose
• The README clearly explains that this is an API service for providing transit information (lines, routes, stops, vehicles, alerts, and more) by processing an official GTFS feed.
• The project is structured as a multi-app (almost microservices-like) monorepo, with multiple applications under the “apps” folder that include the main API server as well as several “sync” and “switch” services.
• Its goal is to serve real-time and static transit data to client applications (e.g., web or mobile apps).
File Structure to Recognize Key Architectural Areas
• apps/sync-* folders (sync-alerts, sync-facilities, sync-gtfs, sync-locations, sync-metrics, sync-stores, sync-vehicles): These appear to be microservices or scheduled tasks responsible for synchronizing data, likely importing or updating data from the official GTFS feed or other sources.
• apps/switch: Although its exact purpose isn’t immediately obvious, its placement and the naming suggest it might be handling routing or toggling between different operational modes or data pipelines.
• packages folder: Contains shared libraries or modules such as “services” (for database or external service integrations like Redis, Mongo, Trino, etc.), “settings”, “types”, “utils” and common TypeScript configurations.
• CI/CD pipelines are defined as GitHub workflows (.github/workflows).
Main Components
a. API Server:
– Represent the “Server” component (apps/server) that manages the public API endpoints described in the README.
b. Sync Services:
c. Switch Service:
– Represent the “Switch” component (apps/switch) as a specialized handler that may manage additional processing or routing logic.
d. Shared Packages and Services:
– Include a block for shared libraries (from packages/services, packages/settings, packages/types, packages/utils) which provide common functionality (integration with external databases such as MongoDB, Redis, Trino, handling GTFS data, etc.).
e. Infrastructure and External Integrations:
– Include a Load Balancer / Reverse Proxy (nginx, as seen in the nginx folder) which fronts the API.
– Display external dependencies/resources:
• The official GTFS feed (data source from Carris Metropolitana GTFS GitHub repository).
• External databases or caches (if used in packages/services, e.g., redis.service.ts, mongo.service.ts, trino.service.ts).
f. Container and Deployment Elements:
– Add a container orchestration layer (docker-compose) that coordinates all microservices. Show how each app (server, sync services, switch) runs in its own Docker container.
– Indicate that CI/CD pipelines (using GitHub workflows) are used for building and deploying images.
Relationships and Interactions
– Clients send HTTP requests to the API server via the load balancer.
– The API Server queries shared services (via packages/services) or databases.
– Sync services running in parallel update the database or data storage which the API server then reads from to serve requests.
– The Switch service interacts with the API server and/or sync tasks to possibly manage data flows.
– External integrations (GTFS feed source, external databases) are connected to the sync services and/or shared service layer.
Architectural Patterns and Design Principles
• Microservices / Modular Design: The separation of the API server and multiple sync tasks suggests a microservices-like architecture.
• Containerization: Each app has its own Dockerfile which shows adherence to containerization best practices.
• Separation of Concerns: Different directories (endpoints, services, tasks) indicate a clear separation between API handling and background processing.