Skip to content

Commit 3d35f72

Browse files
rviannaoliveiraclaude
rviannaoliveira
and
claude
committed
chore: add CLAUDE.md with project instructions for AI agents
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 1a1a44f commit 3d35f72

1 file changed

Lines changed: 116 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# CraftD — Claude Instructions
2+
3+
## O que é o projeto
4+
5+
CraftD é uma biblioteca de **Server Driven UI** multiplatforma. O servidor decide quais componentes renderizar e como; o cliente (app) apenas executa. Suporta:
6+
7+
- Android Compose (`android_kmp/craftd-compose`)
8+
- Android View System / XML (`android_kmp/craftd-xml`)
9+
- KMP Compose Multiplatform (`android_kmp/craftd-compose` via commonMain)
10+
- iOS SwiftUI (`ios/craftd-swiftui`)
11+
- Flutter (`flutter/craftd_widget`)
12+
13+
---
14+
15+
## Estrutura de módulos
16+
17+
```
18+
android_kmp/
19+
craftd-core/ # modelos e abstrações compartilhadas (KMP)
20+
commonMain/ # código compartilhado entre plataformas
21+
androidMain/ # implementações Android-específicas
22+
craftd-compose/ # implementação Compose / KMP
23+
craftd-xml/ # implementação View System (XML)
24+
app-sample-android/ # app de exemplo Android
25+
app-sample-cmp/ # app de exemplo KMP Compose
26+
build-logic/ # configuração de build compartilhada
27+
28+
ios/craftd-swiftui/ # biblioteca iOS (Swift Package + CocoaPods)
29+
flutter/craftd_widget/ # biblioteca Flutter (pub.dev)
30+
docs/ # documentação do site (MkDocs)
31+
```
32+
33+
---
34+
35+
## Regras arquiteturais — nunca violar
36+
37+
1. **Módulos de plataforma não dependem uns dos outros.** `craftd-compose`, `craftd-xml`, `ios/` e `flutter/` dependem apenas do `craftd-core`. Jamais entre si.
38+
39+
2. **Todo novo componente implementa a abstração do platform.** No Android/KMP é `CraftDBuilder`. No iOS é o equivalente Swift. No Flutter é o equivalente Dart. Nunca criar componente avulso fora dessa abstração.
40+
41+
3. **`onAction` / fallback sempre coberto.** Toda implementação de componente deve tratar o callback de ação (`ActionProperties`), mesmo que seja um no-op.
42+
43+
4. **`commonMain` é sagrado.** Código em `commonMain` não pode ter dependências de plataforma. Se precisar de comportamento diferente por plataforma, usa `expect/actual`.
44+
45+
5. **Novos componentes seguem o padrão existente.** Consultar `CraftDButtonBuilder` e `CraftDTextBuilder` como referência de implementação antes de criar algo novo.
46+
47+
6. **Nomes de classes são consistentes entre todas as plataformas.** Ex: se um componente se chama `CraftDImage` no Android, deve se chamar `CraftDImage` em iOS e Flutter também.
48+
49+
7. **Todo novo componente deve ter teste unitário** (quando possível) e **documentação em `docs/` na seção da respectiva plataforma**.
50+
51+
---
52+
53+
## Abstrações principais por plataforma
54+
55+
As três plataformas espelham os mesmos conceitos com nomes equivalentes.
56+
57+
### Android / KMP (Kotlin)
58+
59+
| Classe | Papel |
60+
|---|---|
61+
| `CraftDBuilder` | Interface base para criar componentes |
62+
| `CraftDBuilderManager` | Registra e resolve builders pelo `key` |
63+
| `CraftDynamic` | Composable principal que renderiza o SDUI |
64+
| `SimpleProperties` | Modelo base de dados (`key` + `value` JSON) |
65+
| `ActionProperties` | Dados de ação (deeplink + analytics) |
66+
| `CraftDComponentKey` | Enum com as chaves de componentes built-in |
67+
| `CraftDViewListener` | Callback de ações para o consumidor |
68+
69+
### iOS / SwiftUI (Swift — `ios/craftd-swiftui/`)
70+
71+
| Classe | Papel |
72+
|---|---|
73+
| `CraftDBuilder` | Protocol base para criar componentes |
74+
| `CraftDBuilderManager` | Registra e resolve builders pelo `key` |
75+
| `CraftDynamic` | View principal que renderiza o SDUI |
76+
| `SimpleProperties` | Modelo base de dados |
77+
| `ActionProperties` | Dados de ação (deeplink + analytics) |
78+
| `CraftDViewListener` | Callback de ações para o consumidor |
79+
80+
### Flutter (Dart — `flutter/craftd_widget/`)
81+
82+
| Classe | Papel |
83+
|---|---|
84+
| `CraftDynamic` | Widget principal que renderiza o SDUI |
85+
| `CraftDViewListener` | Callback de ações para o consumidor |
86+
| `SimpleProperties` | Modelo base de dados |
87+
| `ActionProperties` | Dados de ação (deeplink + analytics) |
88+
| `CraftDAlign` | Alinhamento de componentes |
89+
90+
> Ao adicionar um novo componente, ele deve ser implementado nas três plataformas seguindo a mesma abstração de cada uma. Consultar `CraftDButton` / `CraftDButtonBuilder` como referência em todas.
91+
92+
---
93+
94+
## Convenções de código
95+
96+
- **Kotlin:** segue as convenções oficiais do Kotlin. Prefere `data class` para modelos.
97+
- **Nomenclatura de componentes:** prefixo `CraftD` em tudo que é parte da lib (ex: `CraftDButton`, `CraftDButtonBuilder`).
98+
- **Testes:** JUnit4 + MockK. Nomenclatura em backtick: `` `given X when Y then Z` ``. Path espelha o source: `src/test/java/...`
99+
- **Commits:** mensagens em inglês, semânticas (`feat:`, `fix:`, `test:`, `chore:`, `docs:`).
100+
101+
---
102+
103+
## CI / automação
104+
105+
- **`pr.yml`** — build e testes, dispara em todo PR
106+
- **`generate-tests.yml`** — gera testes unitários automaticamente via Claude API para `.kt` modificados, abre PR separado. Só roda após `pr.yml` passar. Não roda em PRs de bots.
107+
108+
---
109+
110+
## O que não fazer
111+
112+
- Não criar componente fora da abstração `CraftDBuilder` (ou equivalente de plataforma)
113+
- Não adicionar dependência de plataforma em `commonMain`
114+
- Não criar dependência entre módulos de plataforma (`craftd-compose` → `craftd-xml`, por exemplo)
115+
- Não commitar `local.properties` nem arquivos de credenciais
116+
- Não usar `--no-verify` para burlar hooks de CI

0 commit comments

Comments
 (0)