docs: add design principles and improve diagrams formatting

Author: getmarkus

.windsurfrules

@@ -0,0 +1,88 @@
+# Design and Principles
+
+- Simple python template I am experimenting with around a set of overlapping concepts with a Fastapi implementation:
+  - Domain Driven Design (DDD)
+  - Clean architecture
+  - Ports & Adapters
+  - Vertical slice
+
+## Core System Components
+
+- The main application logic is in app.
+- Feature flags and configuration settings are in config.py.
+
+## Code styles
+
+- Use PEP 8 and pythonic code
+- Use type hints
+- Functions: Use `snake_case`
+- Variables: Use `snake_case`
+- Constants: Use `UPPER_CASE`
+- Classes: Use `CamelCase`
+- Use `loguru` for logging
+- Use `pydantic` for data validation
+- Use `sqlmodel` for database interactions
+- Use `pydantic-settings` for configuration
+- Use `python-dotenv` for environment variables
+- Use `pytest` for testing
+- Use `pytest-cov` for coverage
+- Use `uv` for dependency management
+
+## Data & Storage
+
+- Support for Sqlite and Postgres via sqlmodel.
+- Use `atlas` for database migrations
+- Use `migrations` directory for migration files
+- Use Bytebase and Supabase style guides
+- Identifier Style: snake_case, lowercase, descriptive
+- Table Names: snake_case, plural, no prefixes, descriptive
+- Column Names: snake_case, singular, descriptive, avoid generic, with `_id`
+- Data Types: Prefer specific types, ENUM for small sets, avoid CHAR(n)
+- Query Formatting: Lowercase keywords, whitespace, clear indentation
+- Functions: Lowercase, snake_case
+- Constraints: Explicit, descriptive names
+
+## Testing & Debugging
+
+- Unit, component and integration tests in app/tests
+- Create unit and component tests first before writing the actual code
+- Follow code implementation with integration tests
+
+## Workflow and developer interaction
+
+- TBD
+
+## Bash commands
+
+- Running api server:
+
+```bash
+uv run fastapi dev main.py
+```
+
+- Running tests:
+
+```bash
+uv run pytest
+```
+
+- Running database and migrations:
+
+```bash
+docker compose up
+docker compose down -v
+```
+
+- Various migration commands depending on database type:
+
+```bash
+atlas schema inspect -u "sqlite://file?cache=shared&mode=memory" --format "{{ sql . }}"
+atlas schema inspect -u "sqlite://issues.db" --format "{{ sql . }}" > migrate.sql
+atlas schema inspect -u "postgres://app_user:change_this_password@localhost:5432/app_database?sslmode=disable" --schema "issue_analysis" --format "{{ sql . }}"
+
+atlas schema apply --url "sqlite://issues.db" --to "file://migrate.sql" --dev-url "sqlite://file?mode=memory" --dry-run
+atlas schema apply --url "sqlite://issues.db" --to "file://migrate.sql" --dev-url "sqlite://file?mode=memory"
+
+atlas schema apply --url "postgres://app_user:change_this_password@localhost:5432/app_database?sslmode=disable" --to "file://./migrations/migrate.sql" --dev-url "docker://postgres/17" --dry-run
+atlas schema apply --url "postgres://app_user:change_this_password@localhost:5432/app_database?sslmode=disable" --to "file://./migrations/migrate.sql" --dev-url "docker://postgres/17"
+```

README.md

@@ -24,28 +24,4 @@ atlas schema apply --url "postgres://app_user:change_this_password@localhost:543
 
 ```mermaid
 graph TD;
-    analyze_endpoint["/issues/{issue_number}/analyze (POST)"] -->|Depends| configure_repository
-    analyze_endpoint -->|Depends| configure_unit_of_work
-    configure_repository -->|Returns| repo["RepositoryProtocol[Issue]"]
-    configure_unit_of_work -->|Returns| uow["UnitOfWork[UnitOfWorkProtocol[ConnectionProtocol]]"]
-    analyze_endpoint --> ApplicationFacade_analyze_issue["ApplicationFacade.analyze_issue()"]
-    ApplicationFacade_analyze_issue --> AnalyzeIssue_constructor["AnalyzeIssue.__init__()"]
-    AnalyzeIssue_constructor --> AnalyzeIssue_analyze["AnalyzeIssue.analyze()"]
-    AnalyzeIssue_analyze --> repo_get_by_id["repo.get_by_id()"]
-    repo_get_by_id -->|Issue found| AnalyzeIssue_analyze
-    repo_get_by_id -->|Issue not found| repo_add["repo.add()"]
-    repo_add --> AnalyzeIssue_analyze
-    configure_unit_of_work --> UnitOfWork_constructor["UnitOfWork.__init__()"]
-    UnitOfWork_constructor --> UnitOfWork_commit["UnitOfWork.commit()"]
-    UnitOfWork_constructor --> UnitOfWork_rollback["UnitOfWork.rollback()"]
-    UnitOfWork_constructor --> UnitOfWork_enter["UnitOfWork.__enter__()"]
-    UnitOfWork_constructor --> UnitOfWork_exit["UnitOfWork.__exit__()"]
-    UnitOfWork_commit --> Connection_commit["Connection.commit()"]
-    UnitOfWork_rollback --> Connection_rollback["Connection.rollback()"]
-    Connection_commit -.-> ConnectionProtocol
-    Connection_rollback -.-> ConnectionProtocol
-    UnitOfWork_commit -.-> UnitOfWorkProtocol
-    UnitOfWork_rollback -.-> UnitOfWorkProtocol
-    UnitOfWork_enter -.-> UnitOfWorkProtocol
-    UnitOfWork_exit -.-> UnitOfWorkProtocol
 ```

diagrams.md

@@ -1,3 +1,5 @@
+# Diagrams
+
 ```mermaid
 graph TD;
     analyze_endpoint["/issues/{issue_number}/analyze (POST)"] -->|Depends| configure_repository
@@ -10,8 +12,10 @@ graph TD;
     AnalyzeIssue_analyze --> repo_get_by_id["repo.get_by_id()"]
     repo_get_by_id -->|Issue found| AnalyzeIssue_analyze
     repo_get_by_id -->|Issue not found| repo_add["repo.add()"]
+
     repo_add --> AnalyzeIssue_analyze
 ```
+
 ```mermaid
 graph TD;
     analyze_endpoint["/issues/{issue_number}/analyze (POST)"] -->|Depends| configure_repository["configure_repository()"]
@@ -38,4 +42,4 @@ graph TD;
     UnitOfWork_rollback -.-> UnitOfWorkProtocol
     UnitOfWork_enter -.-> UnitOfWorkProtocol
     UnitOfWork_exit -.-> UnitOfWorkProtocol
-```
+```