How iduprojects/idu_api works
Project Type and Purpose
• This project is a backend API service built to work with an urban database. It is divided into at least two API applications:
• urban_api: The “Actual API in development to manipulate data in urban_db” (as described in the README).
• city_api: An updated API that replaces an older feature-service, reworking the database schema and microservices.
• In addition, there are utility scripts (in the duty directory) to perform tasks like geometry corrections and regenerating project previews, indicating some scheduled/background processing.
• The system is designed using microservice principles, with distinct modules for handling different aspects (API endpoints, DB migrations, service logic, etc.) and Docker configurations provided for containerized deployment.
Key Components
• Front-facing Services:
• Urban API Service: Handles urban-related API requests and encapsulates endpoints, business logic (controllers, DTOs, service classes, etc.), exception handling, and middlewares.
• City API Service: Focused on manipulating and exposing data from a legacy perspective while transitioning to a microservices-based architecture.
• Core Backend Infrastructure:
• Database: Although not shown as a separate repository, the migrations and DB connection files (e.g., under idu_api/common/db, alembic scripts, and entity definitions) indicate a relational database or similar persistent storage. Show the database as a central component that both APIs interact with.
• DB Migration/ORM Layer: Modules for migrations, entity definitions, and connection managers are essential part of the persistence layer.
• Utility Scripts and Background Tasks:
• Duty Scripts: These include tasks like “fix_geometries” and “regenerate_projects_previews”, which interact with the database or file system. Represent these as a background processing component.
• Deployment and Containerization:
• Dockerfiles and docker-compose files for both urban_api and city_api (as well as the migration runners or testing environments) indicate containerized deployment. Represent these as part of the deployment infrastructure.
Architectural Relationships and Flow
• Urban API and City API:
• These services likely share common lower-level modules (via idu_api) such as configuration and DB connection management, so include a common shared component representing “idu_api Common Modules”.
• Database Layer:
• Sub-components representing the DB migration tools (alembic scripts and entity definitions).
• Utility / Task Schedulers (Duty Scripts):
• How these scripts are triggered possibly on a schedule or via external trigger, interacting directly with the database and file systems to update or correct data.
• External Dependencies:
• If appropriate, note additional external services or libraries such as Prometheus for metrics gathering, given the existence of the "prometheus" files, and note integration with Minio (evidence from minio.env and associated client utilities) for object storage.
Design Patterns and Technologies
• The architecture leverages a modular design separated by concern. You see clear layers:
• API Layer (handlers, controllers, routes),
• Business Logic/Services Layer (service modules, mappers, DTOs),
• Data Access Layer (database connection managers and ORM-like patterns),
• Background Task Layer (duty scripts).
• Use dependency injection (visible in “dependency_injection.py” and middleware) and robust exception handling patterns (present in “exception_handler.py” and corresponding exception directories).
• Adoption of containerization (Docker, docker-compose) stresses the importance of deployment consistency across environments.
• Technologies likely include FastAPI (based on file naming and folder structure), Alembic for DB migrations, and additional libraries for logging, authentication, and metrics.
Final Recommendations
• Remember that clarity is key: simplicity in presentation (even if the internal component responsibilities are complex) will help stakeholders and fellow engineers understand the system quickly.