Skip to content

Commit 8c36dd0

Browse files
PenguinzTechPenguinzTech
committed
Updating documentation to new base standard
1 parent 61bdf6a commit 8c36dd0

9 files changed

Lines changed: 1074 additions & 37 deletions

File tree

‎.claude/mobile.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Mobile App Standards
2+
3+
## ⚠️ CRITICAL RULES
4+
5+
- **DO NOT assume a mobile app exists** - only build one when explicitly requested
6+
- **Flutter is the DEFAULT framework** for all mobile applications - no exceptions unless stated
7+
- **Target BOTH iOS and Android** - every mobile app ships on both platforms
8+
- **Support phones AND tablets** - all layouts must be responsive across phone and tablet form factors on both platforms
9+
- **Native modules are permitted** only when Flutter lacks support for a specific capability
10+
- **Dart linting required** - all code must pass `flutter analyze` before commit
11+
- **Platform testing required** - test on iOS and Android devices/emulators for both phone and tablet screen sizes
12+
13+
## When to Build a Mobile App
14+
15+
**Only build a mobile app when the user or project requirements explicitly call for one.** Mobile apps are not part of the default project template. The standard three-container architecture (WebUI, API, Go backend) does not include a mobile client.
16+
17+
**Indicators that a mobile app is needed:**
18+
- User explicitly requests a mobile app
19+
- Requirements document specifies iOS/Android support
20+
- Project scope includes native device features (push notifications, camera, biometrics, etc.)
21+
22+
**If unclear, ask before creating any mobile app scaffolding.**
23+
24+
## Technology Stack
25+
26+
**Framework: Flutter (Default)**
27+
- Flutter SDK (latest stable channel)
28+
- Dart language (version aligned with Flutter SDK)
29+
- Cross-platform: single codebase for iOS and Android
30+
31+
**When to Use Native Modules:**
32+
- Flutter has no plugin or package for the required functionality
33+
- Existing Flutter plugins are unmaintained, unstable, or lack critical features
34+
- Performance-critical operations that require direct platform API access (e.g., low-level Bluetooth, custom camera pipelines, real-time audio processing)
35+
- Platform-specific APIs with no Flutter equivalent (e.g., certain HealthKit/Health Connect features, NFC advanced modes, platform-specific accessibility APIs)
36+
37+
**Native module approach:**
38+
- Use Flutter platform channels (`MethodChannel`, `EventChannel`) to bridge native code
39+
- Write native code in Swift for iOS, Kotlin for Android
40+
- Keep native code minimal - only what Flutter cannot do
41+
- Document every native module with justification for why Flutter was insufficient
42+
43+
## Project Structure
44+
45+
```
46+
services/mobile/
47+
├── lib/
48+
│ ├── main.dart # App entry point
49+
│ ├── app.dart # App widget, routing, theme
50+
│ ├── config/ # Environment, constants
51+
│ ├── models/ # Data models
52+
│ ├── services/ # API client, auth, storage
53+
│ ├── providers/ # State management
54+
│ ├── screens/ # Page-level widgets
55+
│ ├── widgets/ # Reusable UI components
56+
│ └── utils/ # Helpers, extensions
57+
├── android/ # Android native project
58+
├── ios/ # iOS native project
59+
├── test/ # Unit and widget tests
60+
├── integration_test/ # Integration tests
61+
├── pubspec.yaml # Dependencies
62+
├── analysis_options.yaml # Lint rules
63+
└── Dockerfile # CI build environment
64+
```
65+
66+
## Platform & Device Support
67+
68+
**Platforms:**
69+
| Platform | Language (Native Modules) | Min Version |
70+
|----------|--------------------------|-------------|
71+
| iOS | Swift | iOS 15+ |
72+
| Android | Kotlin | API 24+ (Android 7.0) |
73+
74+
**Form Factors:**
75+
| Device | Breakpoint | Layout Expectations |
76+
|---------|---------------|---------------------|
77+
| Phone | < 600dp wide | Single-column, bottom navigation |
78+
| Tablet | >= 600dp wide | Multi-pane, side navigation, master-detail |
79+
80+
**Responsive layout is mandatory.** Use `LayoutBuilder` or `MediaQuery` to adapt UI across form factors. Never hardcode widths or assume a single device size.
81+
82+
## API Integration
83+
84+
The mobile app communicates with the same Flask backend API used by the WebUI:
85+
86+
```dart
87+
// lib/services/api_client.dart
88+
import 'package:dio/dio.dart';
89+
90+
class ApiClient {
91+
final Dio _dio;
92+
93+
ApiClient({required String baseUrl})
94+
: _dio = Dio(BaseOptions(
95+
baseUrl: baseUrl,
96+
headers: {'Content-Type': 'application/json'},
97+
)) {
98+
_dio.interceptors.add(InterceptorsWrapper(
99+
onRequest: (options, handler) {
100+
final token = AuthService.instance.token;
101+
if (token != null) {
102+
options.headers['Authorization'] = 'Bearer $token';
103+
}
104+
handler.next(options);
105+
},
106+
onError: (error, handler) {
107+
if (error.response?.statusCode == 401) {
108+
AuthService.instance.logout();
109+
}
110+
handler.next(error);
111+
},
112+
));
113+
}
114+
}
115+
```
116+
117+
**API versioning:** Use the same `/api/v{major}/endpoint` pattern as web clients.
118+
119+
## State Management
120+
121+
**Recommended:** `provider` or `riverpod` for state management. Choose one per project and use it consistently.
122+
123+
- `provider` - simpler apps with straightforward state
124+
- `riverpod` - complex apps needing compile-safe dependency injection
125+
126+
## Authentication
127+
128+
Use the same Flask-Security-Too backend as the WebUI. The mobile app should support:
129+
- JWT token storage (secure storage, not shared preferences)
130+
- Biometric authentication (fingerprint, face) via `local_auth` plugin
131+
- MFA/2FA support matching the web flow
132+
- Token refresh on 401 responses
133+
134+
**Secure storage:**
135+
```dart
136+
// Use flutter_secure_storage for tokens - never SharedPreferences
137+
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
138+
139+
final storage = FlutterSecureStorage();
140+
await storage.write(key: 'authToken', value: token);
141+
```
142+
143+
## Design & Theming
144+
145+
Follow the same design language as the WebUI where appropriate:
146+
- Dark theme default with gold/amber accents
147+
- Use `ThemeData` for consistent styling
148+
- Material Design 3 as the base design system
149+
- Platform-adaptive widgets where appropriate (Cupertino on iOS for native feel is acceptable)
150+
151+
**Tablet layouts must differ from phone layouts.** Use adaptive layouts:
152+
- Phone: bottom navigation bar, single-column content
153+
- Tablet: navigation rail or side drawer, multi-pane layouts, master-detail patterns
154+
155+
## Testing
156+
157+
**Required test coverage:**
158+
- Unit tests for models, services, and business logic
159+
- Widget tests for UI components
160+
- Integration tests for critical user flows
161+
- Test on both phone and tablet emulators for each platform
162+
163+
```bash
164+
# Run all tests
165+
flutter test
166+
167+
# Run integration tests
168+
flutter test integration_test/
169+
170+
# Analyze code
171+
flutter analyze
172+
```
173+
174+
**Device matrix for testing:**
175+
| Platform | Phone Emulator | Tablet Emulator |
176+
|----------|----------------------|----------------------|
177+
| iOS | iPhone 15 | iPad Pro 12.9" |
178+
| Android | Pixel 8 | Pixel Tablet |
179+
180+
## Build & Distribution
181+
182+
```bash
183+
# Build for both platforms
184+
flutter build apk --release # Android APK
185+
flutter build appbundle --release # Android App Bundle (Play Store)
186+
flutter build ipa --release # iOS (requires macOS)
187+
```
188+
189+
**CI builds** use a Debian-based Docker image with Flutter SDK for Android builds. iOS builds require a macOS runner (GitHub Actions `macos-latest`).
190+
191+
## Linting & Code Quality
192+
193+
**analysis_options.yaml:**
194+
```yaml
195+
include: package:flutter_lints/flutter.yaml
196+
197+
linter:
198+
rules:
199+
prefer_const_constructors: true
200+
prefer_const_literals_to_create_immutables: true
201+
avoid_print: true
202+
prefer_single_quotes: true
203+
sort_child_properties_last: true
204+
use_build_context_synchronously: true
205+
```
206+
207+
**Run before every commit:**
208+
```bash
209+
flutter analyze # Static analysis
210+
dart format --set-exit-if-changed . # Formatting
211+
flutter test # All tests
212+
```
213+
214+
## Native Module Guidelines
215+
216+
When a native module is necessary:
217+
218+
1. **Document the justification** - add a comment in the native code and a note in the project's `APP_STANDARDS.md` explaining why Flutter alone is insufficient
219+
2. **Keep native code minimal** - only implement what Flutter cannot handle; all other logic stays in Dart
220+
3. **Use platform channels** - `MethodChannel` for request/response, `EventChannel` for streams
221+
4. **Write for both platforms** - every native module must have both Swift (iOS) and Kotlin (Android) implementations
222+
5. **Test native code** - include platform-specific tests (XCTest for iOS, JUnit for Android)
223+
224+
**Example platform channel:**
225+
```dart
226+
// lib/services/native_bridge.dart
227+
import 'package:flutter/services.dart';
228+
229+
class NativeBridge {
230+
static const _channel = MethodChannel('com.penguintech.app/native');
231+
232+
static Future<String?> getPlatformSpecificData() async {
233+
return await _channel.invokeMethod('getPlatformSpecificData');
234+
}
235+
}
236+
```
237+
238+
## Security
239+
240+
- Store tokens in platform secure storage (Keychain on iOS, EncryptedSharedPreferences on Android)
241+
- Enable certificate pinning for API connections in production
242+
- Obfuscate release builds (`flutter build apk --obfuscate --split-debug-info=build/debug-info`)
243+
- No hardcoded secrets, API keys, or credentials in Dart or native code
244+
- Use environment configuration for API URLs and feature flags

‎.claude/orchestration.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Orchestration & Task Agent Rules
2+
3+
## ⚠️ CRITICAL — READ BEFORE DOING ANY WORK
4+
5+
**The main model (Opus or Sonnet) is the orchestrator. It does NOT do the work.**
6+
7+
This is the single most important rule for token efficiency. The main model — whether Opus or Sonnet — exists to plan, delegate, and validate. All actual implementation is performed by task agents.
8+
9+
## The Orchestration Model
10+
11+
The main model's job:
12+
1. **Plan** — Understand the request, break it into tasks, decide approach
13+
2. **Delegate** — Spawn task agents (Haiku by default) to do all implementation work
14+
3. **Validate** — Review task agent output for correctness
15+
4. **Synthesize** — Combine results and communicate back to the user
16+
17+
The main model does NOT:
18+
- Write code directly
19+
- Edit files directly
20+
- Perform searches or grep operations directly (use Explore agents)
21+
- Read large files to extract information (delegate to a task agent)
22+
- Run builds or tests directly (delegate to a Bash task agent)
23+
- Run linting, security scans, or any validation commands directly
24+
25+
**Builds, tests, and validation are task agent work.** The main model never runs `make build`, `npm test`, `flutter test`, `docker compose up`, `pytest`, or similar commands itself. Delegate these to a task agent and have it report back a summary: pass/fail, error count, and any failure details. The main model then decides what to do next based on that summary.
26+
27+
**The only exception**: Trivial single-line operations (reading a small config, quick git status) where spawning an agent would be slower than doing it directly.
28+
29+
## Model Selection for Task Agents
30+
31+
### Haiku — The Default Worker
32+
33+
**Always start with Haiku.** It handles the vast majority of tasks:
34+
- File searches and exploration
35+
- Code edits (add, modify, delete)
36+
- Writing new files
37+
- Running builds (`make build`, `docker compose build`, `flutter build`, etc.)
38+
- Running tests (`pytest`, `npm test`, `flutter test`, `go test`, etc.)
39+
- Running linters and security scans (`eslint`, `flake8`, `bandit`, `gosec`, etc.)
40+
- Reading files and extracting information
41+
- Simple refactoring
42+
- Grep/glob operations
43+
- Documentation updates
44+
45+
**Builds and tests especially** must be run by task agents. The agent runs the command, captures the output, and reports back a summary: pass/fail, error count, and any failure messages. The main model never sees raw build/test output — only the agent's summary.
46+
47+
### Sonnet — Escalation Only
48+
49+
Escalate to Sonnet ONLY when:
50+
- Haiku produced incorrect output and a retry also failed
51+
- The task requires reasoning across many interconnected files
52+
- Complex architectural decisions that need deep analysis
53+
- Intricate refactoring with subtle dependency chains
54+
- Multi-step logic where Haiku demonstrably struggles
55+
56+
**Never start with Sonnet.** Always try Haiku first. If Haiku fails:
57+
1. Retry the Haiku agent once with a clearer/more specific prompt
58+
2. If still failing, escalate to Sonnet with the same prompt + context about what Haiku got wrong
59+
60+
### Opus/Main Model — Never the Worker
61+
62+
The main model never does implementation work regardless of whether it's Opus or Sonnet. Even if you're running Sonnet as the main model, it still orchestrates — it does not write code directly.
63+
64+
## Task Agent Output Rules
65+
66+
**This prevents context overruns that degrade orchestrator performance.**
67+
68+
### What Task Agents MUST Return
69+
70+
- Error messages (if any)
71+
- Brief completion summary (1-3 sentences)
72+
- File paths that were changed
73+
- Line numbers relevant to the change
74+
- Pass/fail status
75+
76+
### What Task Agents MUST NOT Return
77+
78+
- Full file contents
79+
- Verbose explanations of what the code does
80+
- Raw command output (unless it contains errors)
81+
- Unchanged file contents
82+
- Lengthy analysis or commentary
83+
84+
### How to Enforce This
85+
86+
Every task agent prompt MUST include one of these instructions:
87+
- "Return only errors and a brief summary of what was done."
88+
- "Return file paths changed and any errors. No full file contents."
89+
- "Keep your response concise — errors and summary only."
90+
91+
### Example Prompts
92+
93+
**Good prompt:**
94+
```
95+
Edit /path/to/file.py to add input validation to the create_user function.
96+
Validate that email is non-empty and matches a basic email pattern.
97+
Return only errors and a brief summary of what was changed.
98+
```
99+
100+
**Bad prompt:**
101+
```
102+
Edit /path/to/file.py to add input validation to the create_user function.
103+
Show me the full file after changes.
104+
```
105+
106+
## Plans Must Reference This Pattern
107+
108+
Every implementation plan created by the orchestrator MUST include a section like:
109+
110+
```
111+
## Orchestration
112+
- Main model: plans and validates only — does NOT write code, run builds, or run tests
113+
- Task agents: Haiku (default), Sonnet (escalation only)
114+
- Builds/tests: run by task agents, report pass/fail summary back to main model
115+
- Agent output: errors and brief summaries only — no full file contents or raw command output
116+
```
117+
118+
This ensures the pattern is visible and followed throughout execution.
119+
120+
## Concurrency
121+
122+
- Maximum 10 task agents running concurrently
123+
- Parallelize independent work (searching multiple dirs, editing unrelated files)
124+
- Sequence dependent work (read file → edit file → validate edit)
125+
- Queue additional tasks if at the 10-agent limit
126+
127+
## Token Budget Awareness
128+
129+
The reason for all of these rules:
130+
- **Opus/Sonnet tokens are expensive** — don't waste them writing code that Haiku can write
131+
- **Large agent responses bloat context** — the orchestrator's context window fills up, degrading its planning ability
132+
- **Context overruns cause failures** — when the orchestrator can't see its own prior work, it makes mistakes
133+
- **Haiku is fast and cheap** — use it aggressively for all implementation tasks
134+
- **Sonnet is the middle ground** — capable but still cheaper than Opus, use for genuine complexity only

0 commit comments

Comments
 (0)