Claudio Ortolina
303 lines
12 KiB
Markdown
303 lines
12 KiB
Markdown
# Project architecture
|
|
|
|
@docs/architecture.md
|
|
|
|
# Project conventions
|
|
|
|
@docs/project-conventions.md
|
|
|
|
# Production infrastructure
|
|
|
|
@docs/production-infrastructure.md
|
|
|
|
# Commands and tasks
|
|
|
|
The project uses [mise](https://mise.jdx.dev/) to manage high level configuration and tasks.
|
|
|
|
@docs/available-tasks.md
|
|
|
|
## When to read each reference
|
|
|
|
- **Read `docs/architecture.md`** before adding/removing modules, schemas, contexts, workers, routes, or external API integrations. Also read it when asked about the supervision tree, database layout, PubSub topics, or how any two parts of the system connect.
|
|
- **Read `docs/project-conventions.md`** before writing or refactoring code. Also read it when asked about project style, testing patterns, error handling, SQL optimization, commit messages, or JavaScript conventions.
|
|
- **Read `docs/production-infrastructure.md`** before changing deployment config, CI/CD, environment variables, Dockerfiles, or backup strategy. Also read it when asked about hosting, Litestream, Coolify, or production monitoring.
|
|
- **Read `docs/available-tasks.md`** before running mise tasks. Read the file to see available tasks, then run `mise run <task> --help` for task-specific options.
|
|
- **Read `presto/AGENTS.md`** before changing anything in the `presto/` directory. Also read it when the user mentions "presto", the Pimoroni Presto device, MicroPython, or touch display.
|
|
|
|
<!-- usage-rules-start -->
|
|
<!-- usage_rules-start -->
|
|
## usage_rules usage
|
|
_A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies_
|
|
|
|
## Using Usage Rules
|
|
|
|
Many packages have usage rules, which you should *thoroughly* consult before taking any
|
|
action. These usage rules contain guidelines and rules *directly from the package authors*.
|
|
They are your best source of knowledge for making decisions.
|
|
|
|
## Modules & functions in the current app and dependencies
|
|
|
|
When looking for docs for modules & functions that are dependencies of the current project,
|
|
or for Elixir itself, use `mix usage_rules.docs`
|
|
|
|
```
|
|
# Search a whole module
|
|
mix usage_rules.docs Enum
|
|
|
|
# Search a specific function
|
|
mix usage_rules.docs Enum.zip
|
|
|
|
# Search a specific function & arity
|
|
mix usage_rules.docs Enum.zip/1
|
|
```
|
|
|
|
|
|
## Searching Documentation
|
|
|
|
You should also consult the documentation of any tools you are using, early and often. The best
|
|
way to accomplish this is to use the `usage_rules.search_docs` mix task. Once you have
|
|
found what you are looking for, use the links in the search results to get more detail. For example:
|
|
|
|
```
|
|
# Search docs for all packages in the current application, including Elixir
|
|
mix usage_rules.search_docs Enum.zip
|
|
|
|
# Search docs for specific packages
|
|
mix usage_rules.search_docs Req.get -p req
|
|
|
|
# Search docs for multi-word queries
|
|
mix usage_rules.search_docs "making requests" -p req
|
|
|
|
# Search only in titles (useful for finding specific functions/modules)
|
|
mix usage_rules.search_docs "Enum.zip" --query-by title
|
|
```
|
|
|
|
|
|
<!-- usage_rules-end -->
|
|
<!-- usage_rules:elixir-start -->
|
|
## usage_rules:elixir usage
|
|
# Elixir Core Usage Rules
|
|
|
|
## Pattern Matching
|
|
- Use pattern matching over conditional logic when possible
|
|
- Prefer to match on function heads instead of using `if`/`else` or `case` in function bodies
|
|
- `%{}` matches ANY map, not just empty maps. Use `map_size(map) == 0` guard to check for truly empty maps
|
|
|
|
## Error Handling
|
|
- Use `{:ok, result}` and `{:error, reason}` tuples for operations that can fail
|
|
- Avoid raising exceptions for control flow
|
|
- Use `with` for chaining operations that return `{:ok, _}` or `{:error, _}`
|
|
|
|
## Common Mistakes to Avoid
|
|
- Elixir has no `return` statement, nor early returns. The last expression in a block is always returned.
|
|
- Don't use `Enum` functions on large collections when `Stream` is more appropriate
|
|
- Avoid nested `case` statements - refactor to a single `case`, `with` or separate functions
|
|
- Don't use `String.to_atom/1` on user input (memory leak risk)
|
|
- Lists and enumerables cannot be indexed with brackets. Use pattern matching or `Enum` functions
|
|
- Prefer `Enum` functions like `Enum.reduce` over recursion
|
|
- When recursion is necessary, prefer to use pattern matching in function heads for base case detection
|
|
- Using the process dictionary is typically a sign of unidiomatic code
|
|
- Only use macros if explicitly requested
|
|
- There are many useful standard library functions, prefer to use them where possible
|
|
|
|
## Function Design
|
|
- Use guard clauses: `when is_binary(name) and byte_size(name) > 0`
|
|
- Prefer multiple function clauses over complex conditional logic
|
|
- Name functions descriptively: `calculate_total_price/2` not `calc/2`
|
|
- Predicate function names should not start with `is` and should end in a question mark.
|
|
- Names like `is_thing` should be reserved for guards
|
|
|
|
## Data Structures
|
|
- Use structs over maps when the shape is known: `defstruct [:name, :age]`
|
|
- Prefer keyword lists for options: `[timeout: 5000, retries: 3]`
|
|
- Use maps for dynamic key-value data
|
|
- Prefer to prepend to lists `[new | list]` not `list ++ [new]`
|
|
|
|
## Mix Tasks
|
|
|
|
- Use `mix help` to list available mix tasks
|
|
- Use `mix help task_name` to get docs for an individual task
|
|
- Read the docs and options fully before using tasks
|
|
|
|
## Testing
|
|
- Run tests in a specific file with `mix test test/my_test.exs` and a specific test with the line number `mix test path/to/test.exs:123`
|
|
- Limit the number of failed tests with `mix test --max-failures n`
|
|
- Use `@tag` to tag specific tests, and `mix test --only tag` to run only those tests
|
|
- Use `assert_raise` for testing expected exceptions: `assert_raise ArgumentError, fn -> invalid_function() end`
|
|
- Use `mix help test` to for full documentation on running tests
|
|
|
|
## Debugging
|
|
|
|
- Use `dbg/1` to print values while debugging. This will display the formatted value and other relevant information in the console.
|
|
|
|
<!-- usage_rules:elixir-end -->
|
|
<!-- usage_rules:otp-start -->
|
|
## usage_rules:otp usage
|
|
# OTP Usage Rules
|
|
|
|
## GenServer Best Practices
|
|
- Keep state simple and serializable
|
|
- Handle all expected messages explicitly
|
|
- Use `handle_continue/2` for post-init work
|
|
- Implement proper cleanup in `terminate/2` when necessary
|
|
|
|
## Process Communication
|
|
- Use `GenServer.call/3` for synchronous requests expecting replies
|
|
- Use `GenServer.cast/2` for fire-and-forget messages.
|
|
- When in doubt, use `call` over `cast`, to ensure back-pressure
|
|
- Set appropriate timeouts for `call/3` operations
|
|
|
|
## Fault Tolerance
|
|
- Set up processes such that they can handle crashing and being restarted by supervisors
|
|
- Use `:max_restarts` and `:max_seconds` to prevent restart loops
|
|
|
|
## Task and Async
|
|
- Use `Task.Supervisor` for better fault tolerance
|
|
- Handle task failures with `Task.yield/2` or `Task.shutdown/2`
|
|
- Set appropriate task timeouts
|
|
- Use `Task.async_stream/3` for concurrent enumeration with back-pressure
|
|
|
|
<!-- usage_rules:otp-end -->
|
|
<!-- usage_rules-start -->
|
|
## usage_rules usage
|
|
_A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies_
|
|
|
|
## Using Usage Rules
|
|
|
|
Many packages have usage rules, which you should *thoroughly* consult before taking any
|
|
action. These usage rules contain guidelines and rules *directly from the package authors*.
|
|
They are your best source of knowledge for making decisions.
|
|
|
|
## Modules & functions in the current app and dependencies
|
|
|
|
When looking for docs for modules & functions that are dependencies of the current project,
|
|
or for Elixir itself, use `mix usage_rules.docs`
|
|
|
|
```
|
|
# Search a whole module
|
|
mix usage_rules.docs Enum
|
|
|
|
# Search a specific function
|
|
mix usage_rules.docs Enum.zip
|
|
|
|
# Search a specific function & arity
|
|
mix usage_rules.docs Enum.zip/1
|
|
```
|
|
|
|
|
|
## Searching Documentation
|
|
|
|
You should also consult the documentation of any tools you are using, early and often. The best
|
|
way to accomplish this is to use the `usage_rules.search_docs` mix task. Once you have
|
|
found what you are looking for, use the links in the search results to get more detail. For example:
|
|
|
|
```
|
|
# Search docs for all packages in the current application, including Elixir
|
|
mix usage_rules.search_docs Enum.zip
|
|
|
|
# Search docs for specific packages
|
|
mix usage_rules.search_docs Req.get -p req
|
|
|
|
# Search docs for multi-word queries
|
|
mix usage_rules.search_docs "making requests" -p req
|
|
|
|
# Search only in titles (useful for finding specific functions/modules)
|
|
mix usage_rules.search_docs "Enum.zip" --query-by title
|
|
```
|
|
|
|
|
|
<!-- usage_rules-end -->
|
|
<!-- usage_rules:elixir-start -->
|
|
## usage_rules:elixir usage
|
|
# Elixir Core Usage Rules
|
|
|
|
## Pattern Matching
|
|
- Use pattern matching over conditional logic when possible
|
|
- Prefer to match on function heads instead of using `if`/`else` or `case` in function bodies
|
|
- `%{}` matches ANY map, not just empty maps. Use `map_size(map) == 0` guard to check for truly empty maps
|
|
|
|
## Error Handling
|
|
- Use `{:ok, result}` and `{:error, reason}` tuples for operations that can fail
|
|
- Avoid raising exceptions for control flow
|
|
- Use `with` for chaining operations that return `{:ok, _}` or `{:error, _}`
|
|
|
|
## Common Mistakes to Avoid
|
|
- Elixir has no `return` statement, nor early returns. The last expression in a block is always returned.
|
|
- Don't use `Enum` functions on large collections when `Stream` is more appropriate
|
|
- Avoid nested `case` statements - refactor to a single `case`, `with` or separate functions
|
|
- Don't use `String.to_atom/1` on user input (memory leak risk)
|
|
- Lists and enumerables cannot be indexed with brackets. Use pattern matching or `Enum` functions
|
|
- Prefer `Enum` functions like `Enum.reduce` over recursion
|
|
- When recursion is necessary, prefer to use pattern matching in function heads for base case detection
|
|
- Using the process dictionary is typically a sign of unidiomatic code
|
|
- Only use macros if explicitly requested
|
|
- There are many useful standard library functions, prefer to use them where possible
|
|
|
|
## Function Design
|
|
- Use guard clauses: `when is_binary(name) and byte_size(name) > 0`
|
|
- Prefer multiple function clauses over complex conditional logic
|
|
- Name functions descriptively: `calculate_total_price/2` not `calc/2`
|
|
- Predicate function names should not start with `is` and should end in a question mark.
|
|
- Names like `is_thing` should be reserved for guards
|
|
|
|
## Data Structures
|
|
- Use structs over maps when the shape is known: `defstruct [:name, :age]`
|
|
- Prefer keyword lists for options: `[timeout: 5000, retries: 3]`
|
|
- Use maps for dynamic key-value data
|
|
- Prefer to prepend to lists `[new | list]` not `list ++ [new]`
|
|
|
|
## Mix Tasks
|
|
|
|
- Use `mix help` to list available mix tasks
|
|
- Use `mix help task_name` to get docs for an individual task
|
|
- Read the docs and options fully before using tasks
|
|
|
|
## Testing
|
|
- Run tests in a specific file with `mix test test/my_test.exs` and a specific test with the line number `mix test path/to/test.exs:123`
|
|
- Limit the number of failed tests with `mix test --max-failures n`
|
|
- Use `@tag` to tag specific tests, and `mix test --only tag` to run only those tests
|
|
- Use `assert_raise` for testing expected exceptions: `assert_raise ArgumentError, fn -> invalid_function() end`
|
|
- Use `mix help test` to for full documentation on running tests
|
|
|
|
## Debugging
|
|
|
|
- Use `dbg/1` to print values while debugging. This will display the formatted value and other relevant information in the console.
|
|
|
|
<!-- usage_rules:elixir-end -->
|
|
<!-- mdex-start -->
|
|
## mdex usage
|
|
_Fast and extensible Markdown for Elixir_
|
|
|
|
@deps/mdex/usage-rules.md
|
|
<!-- mdex-end -->
|
|
<!-- usage-rules-end -->
|
|
|
|
<!-- BACKLOG.MD MCP GUIDELINES START -->
|
|
|
|
<CRITICAL_INSTRUCTION>
|
|
|
|
## BACKLOG WORKFLOW INSTRUCTIONS
|
|
|
|
This project uses Backlog.md MCP for all task and project management activities.
|
|
|
|
**CRITICAL GUIDANCE**
|
|
|
|
- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
|
|
- If your client only supports tools or the above request fails, call `backlog.get_backlog_instructions()` to load the tool-oriented overview. Use the `instruction` selector when you need `task-creation`, `task-execution`, or `task-finalization`.
|
|
|
|
- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
|
|
- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
|
|
- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
|
|
|
|
These guides cover:
|
|
- Decision framework for when to create tasks
|
|
- Search-first workflow to avoid duplicates
|
|
- Links to detailed guides for task creation, execution, and finalization
|
|
- MCP tools reference
|
|
|
|
You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.
|
|
|
|
</CRITICAL_INSTRUCTION>
|
|
|
|
<!-- BACKLOG.MD MCP GUIDELINES END -->
|