From 758a6a8cad525092ee8d1ca69ab7ca0c528d089a Mon Sep 17 00:00:00 2001 From: lucaspaiva-lp Date: Fri, 30 Jan 2026 23:33:00 -0300 Subject: [PATCH] docs: establish project intent, architecture, and evolution docs --- .gitignore | 2 +- CHANGELOG.md | 55 +++++++++++++++ README.md | 164 +++++++++++++++++++++++++++++++++++++++++++ docs/architecture.md | 153 ++++++++++++++++++++++++++-------------- docs/scope.md | 71 ++++++++++--------- 5 files changed, 357 insertions(+), 88 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.gitignore b/.gitignore index 21539d7..8ff8289 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ .vscode/ -CHANGELOG.md + # Ignore python files **/__pycache__ .pytest_cache diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d96b721 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,55 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +This project follows a pragmatic versioning approach during its early development stages. + +--- + +## [Unreleased] + +### Planned + +- Introduce an explicit Application Layer +- Add domain-level validations +- Improve test isolation and database lifecycle handling +- Expand API endpoints beyond basic user operations + +--- + +## [0.1.0] – Initial Architecture and Persistence Setup + +### Added + +- Initial project structure following a layered, MVC-inspired architecture +- Flask server setup with Blueprint-based routing +- SQLite database integration +- SQLAlchemy base configuration +- User entity definition +- User repository with insert and select operations +- Database connection handler abstraction +- Initial database schema definition (`schema.sql`) +- Repository-level tests interacting with the database +- Project documentation: + - README with project intent and boundaries + - Architecture documentation + - Scope definition + +### Changed + +- Adjusted database connection handling to support testing scenarios +- Refined repository tests to better reflect persistence behavior +- Improved project structure to isolate infrastructure concerns + +### Fixed + +- Issues related to repeated data insertion during test execution +- Test failures caused by shared database state +- Missing initialization steps in database setup + +### Notes + +- Business logic is intentionally minimal at this stage +- Routes currently return placeholder responses +- Application Layer is planned but not yet implemented +- Database is treated as a first-class dependency for learning and clarity diff --git a/README.md b/README.md index 184c79f..dfbc2e2 100644 --- a/README.md +++ b/README.md @@ -1 +1,165 @@ + # API_Web + +## Overview + +API_Web is a backend-focused project designed to explore and apply clean architectural principles using a simple and well-defined domain. + +The project prioritizes **clarity, correctness, and maintainability** over feature breadth, serving as an educational and evolvable foundation for backend development. + +--- + +## Problem Statement + +Many small backend projects grow without clear structure, leading to tightly coupled code, unclear responsibilities, and fragile tests. + +This project was created to address those issues by: + +* Applying a clear architectural pattern (MVC) +* Enforcing separation of concerns +* Treating the database as an explicit and controlled dependency +* Encouraging deterministic and understandable behavior + +--- + +## Project Purpose + +The purpose of this project is to provide a **structured backend API** that: + +* Demonstrates clean separation between layers +* Uses explicit contracts between components +* Remains easy to reason about, test, and extend +* Serves as a learning vehicle for real-world backend practices + +Correctness and architectural integrity are prioritized over rapid feature expansion. + +--- + +## Architectural Style + +The project follows the **MVC (Model–View–Controller)** architectural pattern, adapted for a backend API context. + +### MVC Mapping in This Project + +* **Model** + * Domain entities (`models/entities`) + * Database connection and ORM base (`models/connection`) + * Repositories (`models/repositories`) +* **Controller** + * Route handlers and request orchestration (`main/routes`) +* **View** + * JSON responses returned by the API (no UI rendering) + +This structure ensures that business logic, persistence, and request handling remain clearly separated. + +--- + +## Project Structure + +
+ +
src/
+├── database/
+│   └── init/
+│       └── schema.sql
+├── main/
+│   ├── routes/
+│   │   └── user_route.py
+│   └── server/
+│       └── server.py
+├── models/
+│   ├── connection/
+│   │   ├── base.py
+│   │   └── db_connection_handler.py
+│   ├── entities/
+│   │   └── users.py
+│   └── repositories/
+│       └── users_repository.py
+├── __init__.py
+run.py
+
+ +Additional documentation lives in the `docs/` directory. + +--- + +## Scope + +The system focuses on a **small and controlled domain** . + +### In Scope + +* Handling HTTP requests via Flask +* Managing user data through a repository layer +* Interacting with a relational database (SQLite) +* Applying automated tests to persistence logic +* Enforcing architectural boundaries + +### Out of Scope + +* Frontend or UI rendering +* Authentication and authorization +* Distributed systems or messaging +* Performance optimization beyond correctness +* Production-scale deployment concerns + +For more detail, see `docs/scope.md`. + +--- + +## Database + +* **SQLite** is used for simplicity and transparency +* Database schema is defined explicitly (`schema.sql`) +* The database is treated as an external dependency, not implicit state +* Tests may use either in-memory or file-based databases depending on intent + +--- + +## Testing Strategy + +* Repository behavior is validated via automated tests +* Tests are written to highlight the importance of data isolation and state control +* Both isolated and persistent-database scenarios are intentionally explored + +Testing decisions are documented and aligned with the project’s educational goals. + +--- + +## Documentation + +* `docs/architecture.md` — Architectural decisions and layer responsibilities +* `docs/scope.md` — Explicit definition of system scope +* `CHANGELOG.md` — Versioned record of changes +* `SECURITY.md` — Security-related considerations + +--- + +## Non-Goals + +This project does **not** aim to: + +* Be a production-ready system +* Replace full-featured frameworks +* Hide infrastructure complexity behind abstractions +* Optimize prematurely for scalability + +--- + +## Role of This Repository + +This repository serves as: + +* A learning artifact +* A reference for clean backend structure +* A controlled environment to explore architectural trade-offs + +Any significant change in intent or scope **must be reflected in the documentation** . + +## Learning Context + +This project was initially developed following the *Clean Code* course by Rocketseat as a learning reference. + +At this stage, the structure and patterns closely align with the course material, with minor adaptations applied intentionally. + +Future iterations of this project may diverge from the original course approach as architectural decisions evolve independently. diff --git a/docs/architecture.md b/docs/architecture.md index f1208d2..df5d3aa 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,25 +1,32 @@ + # System Architecture ## 1. Architectural Overview -API_Web is structured as a backend service with clear responsibilities and separation of concerns. +API_Web is a backend API structured with explicit separation of concerns and clear responsibility boundaries. + +Even in its early stage, the architecture prioritizes **clarity, maintainability, and controlled evolution**, avoiding hidden coupling and implicit behavior. -The architecture emphasizes **clarity, maintainability, and scalability** , even in its minimal prototype form. +The system is intentionally minimal, but architecturally prepared for growth. --- ## 2. Architectural Style -The system follows a **layered architecture** , where each layer has a well-defined responsibility. +The project follows a **layered architecture**, inspired by MVC principles and adapted to a backend API context. + +Each layer has a single, well-defined responsibility, and dependencies are strictly directional. -Primary layers: +### Logical Layers -* **Interface Layer** – Flask routes / Blueprints -* **Application Layer** – Future orchestration of business rules -* **Domain Layer** – Core logic and validations (currently minimal) -* **Infrastructure Layer** – Database setup, SQLite persistence, external tools +- **Interface Layer** – HTTP handling (Flask routes / Blueprints) +- **Application Layer** – Use case orchestration (planned) +- **Domain Layer** – Core business rules and entities +- **Infrastructure Layer** – Database access and external tooling -Communication is **directional** : Interface → Application → Domain → Infrastructure. +Communication flows inward: + +**Interface → Application → Domain → Infrastructure** --- @@ -27,96 +34,134 @@ Communication is **directional** : Interface → Application → Domain → Inf ### 3.1 Interface Layer -Responsible for: +**Location** + +- `src/main/routes` +- `src/main/server` -* Exposing API endpoints (`/user`) to clients -* Translating HTTP requests into internal actions -* Validating input and formatting JSON responses +**Responsibilities** -**Notes:** +- Expose HTTP endpoints +- Handle request/response lifecycle +- Translate HTTP input into internal calls +- Return JSON responses -* No business logic is implemented yet; responses are placeholders. +**Constraints** + +- No business rules +- No persistence logic +- No domain decisions + +**Current State** + +- Routes are defined using Flask Blueprints +- Responses are currently simple and illustrative --- ### 3.2 Application Layer -Responsible for: +**Location** + +- Planned (to be introduced between routes and repositories) -* Orchestrating use cases (future implementation) -* Coordinating domain operations -* Enforcing workflows +**Responsibilities** -**Notes:** +- Orchestrate use cases +- Coordinate domain operations +- Control application flow -* Currently minimal; will be added when registration logic is implemented. +**Current State** + +- Not implemented yet +- Responsibilities are temporarily handled by routes +- This is an intentional transitional decision --- ### 3.3 Domain Layer -Responsible for: +**Location** + +- `src/models/entities` + +**Responsibilities** -* Core business rules and validations -* Domain invariants (e.g., user age or height constraints) -* Pure logic independent of Flask or database frameworks +- Represent domain entities +- Encapsulate domain rules and invariants +- Remain independent of frameworks and infrastructure -**Notes:** +**Current State** -* Domain layer is empty for now, but will encapsulate rules to allow future scalability. +- Domain entities are defined using SQLAlchemy models +- Business rules are minimal and will evolve incrementally --- ### 3.4 Infrastructure Layer -Responsible for: +**Location** + +- `src/models/connection` +- `src/database` + +**Responsibilities** -* Database persistence (`schema.db` via SQLite) -* SQL schema management (`schema.sql`) -* External integrations (Postman, DBeaver for testing) +- Database connection management +- ORM configuration and persistence +- SQL schema definition +- External tooling support -**Notes:** +**Current State** -* `src/database/__init__.py` handles DB auto-creation -* Infrastructure details are **isolated from domain logic** . +- SQLite is used as the persistence mechanism +- Database schema is explicitly defined in `schema.sql` +- Connection handling is isolated from domain and interface layers --- ## 4. Data Flow -1. HTTP requests hit the **Interface Layer** (Flask route / Blueprint). -2. Interface delegates to **Application Layer** for business workflow. -3. Application Layer interacts with **Domain Layer** for rules and validations. -4. Domain logic requests persistence via the **Infrastructure Layer** . -5. Responses flow in the **opposite direction** to the client. +1. An HTTP request reaches the **Interface Layer** (Flask route). +2. The route delegates processing (currently directly) to repository or future application logic. +3. Domain entities are created or queried. +4. Persistence is handled by the **Infrastructure Layer**. +5. A response is returned to the client. -**Rule:** no layer bypasses another; dependencies point inward. +**Architectural Rule** + +- No layer may bypass another intentionally. +- Dependencies must always point inward. --- ## 5. Technical Constraints -* No business logic in Interface or Infrastructure layers -* Domain logic must remain independent of external frameworks -* SQLite DB is used for local development only -* Project must remain testable without external dependencies +- Business logic must not live in routes or database handlers +- Infrastructure details must not leak into domain logic +- SQLite is used for local development and learning purposes +- The system must remain testable with controlled state --- ## 6. Key Architectural Decisions -* Layered architecture chosen for clarity and maintainability -* Initial phase uses **stateless endpoints** and in-memory data placeholders -* Database persistence isolated to Infrastructure Layer -* Explicit contracts between layers allow future scalability +- Use of layered architecture for clarity and testability +- MVC-inspired structure adapted for backend APIs +- Database treated as an explicit dependency +- Tests may interact with real or isolated databases depending on intent --- ## 7. Architectural Evolution -* New features must follow the layer boundaries -* Major changes must update this document or be recorded in **Decision Records** -* Future enhancements may include: - * Application Layer orchestration - * Service and repository separation - * Additional entities and tables +This architecture is expected to evolve gradually. + +Planned evolutions include: + +- Introduction of an explicit Application Layer +- Clear separation between services and repositories +- Expansion of domain rules and validations +- Support for additional entities and use cases + +All significant architectural changes must be reflected in this document. diff --git a/docs/scope.md b/docs/scope.md index bd6d238..fb09bbc 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -1,72 +1,77 @@ + # System Scope ## 1. Purpose -This document defines the functional scope of **API_Web** , establishing what is included and excluded from the system’s responsibilities. +This document defines the functional and technical scope of API_Web. -It serves as the authoritative reference for feature inclusion during development. +It establishes clear boundaries for what the system is responsible for and prevents uncontrolled feature expansion. --- -## 2. In-Scope +## 2. In Scope The system is responsible for: -* Receiving and validating HTTP client requests via Flask routes -* Exposing endpoints through Flask Blueprints (e.g., `/user`) -* Returning deterministic JSON responses for defined requests -* Initial setup and persistence of SQLite database (`schema.db`) -* Providing a structure for future business rules and domain logic +- Exposing HTTP endpoints via a backend API +- Handling basic request and response flows +- Managing user-related data +- Interacting with a relational database +- Applying automated tests to persistence logic +- Enforcing architectural separation of concerns --- -## 3. Out-of-Scope +## 3. Out of Scope -The system is **not** responsible for: +The system explicitly does **not** handle: -* User interface rendering beyond JSON responses -* Authentication, authorization, or security workflows -* Complex data persistence (currently SQLite only, no production DB) -* External system orchestration beyond defined API endpoints -* Reporting, analytics, or auditing features +- Frontend rendering or UI concerns +- Authentication or authorization +- Advanced validation or complex business rules (for now) +- Distributed systems or messaging +- Performance optimization or scalability tuning +- Production deployment concerns --- ## 4. Supported Use Cases -The system supports the following interactions: +At its current stage, the system supports: + +- Creating user records +- Querying user data by defined criteria +- Validating repository behavior through tests +- Exploring controlled database interactions -* A client submits a valid request to `/user` and receives a success response -* A client submits invalid or incomplete data and receives a validation error -* A client requests an unsupported operation and receives a defined error response -* Integration via documented API interfaces using Postman or other tools +Future use cases will be added incrementally. --- ## 5. Assumptions -The system operates under the following assumptions: +The system assumes that: -* Clients send requests in the documented JSON format -* SQLite database is available and initialized correctly -* The system is executed in a controlled environment (local dev, Docker, or VM) -* Input data adheres to simple domain constraints (e.g., user age, height) +- Requests follow documented formats +- The database schema is under developer control +- The application runs in a local or controlled environment +- Data consistency is managed at the application level --- ## 6. Constraints -The system is subject to the following constraints: +The system must: -* Must operate within a stateless, minimal prototype context -* Must follow Python coding and architectural standards -* SQLite database is for local development only -* Future scaling and production considerations (PostgreSQL, services) are planned but not implemented +- Maintain a small and understandable scope +- Avoid hidden side effects +- Keep persistence explicit and predictable +- Favor clarity over premature optimization --- ## 7. Scope Governance -* Any functionality not explicitly described in this document is considered out of scope -* Changes to scope must be reviewed and documented before implementation -* The initial version is focused on **structure, routing, and DB setup** , not full business logic +Any functionality not explicitly listed in this document is considered out of scope. + +Changes to scope must be deliberate and documented before implementation.