Organizing, editing

Author: marksvc

.github/copilot-instructions.md

@@ -6,72 +6,61 @@ This repository contains three interconnected applications:
 2. Backend (dotnet) that runs on a server, at src/SIL.XForge and src/SIL.XForge.Scripture
 3. RealtimeServer (Node) that runs on a server, at src/RealtimeServer
 
-# Key Architectural Patterns
-
-- Data models must be defined in all 3 applications to stay in sync
-- Frontend uses RealtimeService (ShareDB) for real-time data sync, which is defined at src/SIL.XForge.Scripture/ClientApp/src/xforge-common/realtime.service.ts
-- Frontend also sometimes uses JSON-RPC to communicate with Backend.
-- Frontend works offline and uses IndexedDB for storage.
-- User permissions should be checked on both frontend and backend, using the rights service whenever possible, rather than checking the user role. See project-rights.ts, sf-project-rights.ts, and SFProjectRights.cs.
+# Data exchange between the three interconnected applications
+
+- Data models must be defined in all 3 applications and stay in sync.
+- An example Backend data model can be seen at src/SIL.XForge.Scripture/Models/SFProject.cs
+- Frontend and RealtimeServer both use the same data model files. An example can be seen at src/RealtimeServer/scriptureforge/models/sf-project.ts
+- Frontend uses src/SIL.XForge.Scripture/ClientApp/src/xforge-common/realtime.service.ts to read and write data. This Realtime document data is stored in IndexedDB and is also automatically kept up to date with the data in RealtimeServer when Frontend has an Internet connection. If Frontend is offline, it continues reading and writing realtime documents using realtime.service.ts, and later data is synced with RealtimeService when Frontend regains an Internet connection.
+- Realtime documents should not be modified directly. Instead, submit ops to modify the realtime documents.
+- RealtimeServer uses ShareDB to merge ops from multiple Frontend clients. Frontend clients synchronize with RealtimeServer and present a live view of the changes from other clients as they work.
+- Frontend also uses JSON-RPC to communicate with Backend, such as seen on Backend at src/SIL.XForge.Scripture/Controllers/SFProjectsRpcController.cs.
+- User permissions should be checked in all of Frontend, Backend, and RealtimeServer, using the rights service whenever possible, rather than checking the user role. See project-rights.ts, sf-project-rights.ts, and SFProjectRights.cs.
+- Follow existing patterns for validation schemas.
+
+# Frontend
+
+- Most Frontend tasks should work on a mobile phone. In other words, on a device with a narrow and short screen.
+- Most editing and reviewing tasks should work while offline. Changing some settings may require being online.
+- Feature flags (feature-flag.service.ts) can control functionality rollout.
+- Error handling with ErrorReportingService
+- Keep related files together in feature folders
+- Follow existing naming conventions
 
-# Frontend Guidelines
+# Frontend localization
 
-- Use standalone Angular components with typed inputs/outputs
-- Feature flags (feature-flag.service.ts) can control functionality rollout.
+- Use TranslocoModule for translations
 - Put UI strings in checking_en.json if ANY user might see them
 - Only put strings in non_checking_en.json if community checkers will NEVER see them
-- Use TranslocoModule for translations
-- Prefix async calls that aren't awaited with 'void'
-- Use explicit true/false/null/undefined rather than truthy/falsy
-- Use `@if {}` syntax rather than `*ngIf` syntax.
-
-# Data Layer Guidelines
-
-- Define interfaces/models in all 3 applications
-- Use RealtimeService for CRUD operations
-- Follow existing patterns for validation schemas
+- Localizations that a Community Checker user might see should be created or edited in src/SIL.XForge.Scripture/ClientApp/src/assets/i18n/checking_en.json. Only localizations that a Community Checker user will not see can be created or edited in src/SIL.XForge.Scripture/ClientApp/src/assets/i18n/non_checking_en.json.
+- Even if something is a system-wide feature that isn't specific to community checking functionality, it should still be placed in checking_en.json if a community checking user would POSSIBLY see it.
 
-# Testing Guidelines
+# Testing
 
 - Write unit tests for new components and services
 - Follow existing patterns for mocking dependencies
 - Use TestEnvironment pattern from existing tests
 - Test both online and offline scenarios
 - Test permission boundaries
 
-# Common Patterns to Follow
+# Code comments
 
-- Permission checking in services
-- Error handling with ErrorReportingService
-- Offline-first data access
-- Type-safe data models
-
-# File Organization
-
-- Keep related files together in feature folders
-- Follow existing naming conventions
-
-DO NOT REMOVE COMMENTS ALREADY IN THE CODE. You can add to or edit existing comments, but do not removing the existing comments.
-Do not insert new comments into the code where method calls already make it clear.
-Do not add method comments unless the method would be unclear to an experienced developer.
-Do put comments into the code to make it more clear what is going on if it would not be obvious to an experienced developer.
-Do put comments into the code if the intent is not clear from the code.
-All classes should have a comment to briefly explain why it is there and what its purpose is in the overall system, even if it seems obvious.
-Please do not fail to add a comment to any classes that are created. All classes should have a comment.
+- DO NOT REMOVE COMMENTS ALREADY IN THE CODE. You can add to or edit existing comments, but do not removing the existing comments.
+- Do not insert new comments into the code where method calls already make it clear.
+- Do not add method comments unless the method would be unclear to an experienced developer.
+- Do put comments into the code to make it more clear what is going on if it would not be obvious to an experienced developer.
+- Do put comments into the code if the intent is not clear from the code.
+- All classes should have a comment to briefly explain why it is there and what its purpose is in the overall system, even if it seems obvious.
+- Please do not fail to add a comment to any classes that are created. All classes should have a comment.
 
-Never rely on JavaScript's truthy or falsy. Instead, work with actual true, false, null, and undefined values, rather than relying on their interpretation as truthy or falsy. For example, if `someVariable` might be null, or undefined, or zero, don't write code like `if (someVariable)` or `const foo:string = someVariable ? 'a' : 'b'` or `if (count)`. Instead, inspect for the null, undefined, or zero rather than letting the value be interpreted as truthy for falsy. For example, use`if (someVariable == null)` or `const foo:string = someVariable != null 'a' : 'b'` or `if (count > 0)`.
+# TypeScript language
 
-Specify types where not obvious, such as when declaring variables and arguments, and for function return types.
-
-If you do not have access to a file that you need, stop and ask me.
-
-All code that you write should be able to pass eslint linting tests for TypeScript, or csharpier for C#.
-
-Don't merely write code for the local context, but make changes that are good overall considering the architecture of the application and structure of the files and classes.
-
-The frontend works offline, reading and writing data to and from IndexedDB using src/SIL.XForge.Scripture/ClientApp/src/xforge-common/realtime.service.ts. Do not modify realtime documents directly; instead, submit operations to the realtime documents. Realtime document data is automatically kept up to date with the data on the server when the frontend has an Internet connection. Most of data reading and writing from the frontend should happen by reading Realtime documents and submitting ops to Realtime documents to write to them, with occasional usage of JSON-RPC, such as seen on the C# backend at src/SIL.XForge.Scripture/Controllers/SFProjectsRpcController.cs.
+- Use explicit true/false/null/undefined rather than truthy/falsy
+- Never rely on JavaScript's truthy or falsy. Instead, work with actual true, false, null, and undefined values, rather than relying on their interpretation as truthy or falsy. For example, if `count` might be null, or undefined, or zero, don't write code like `if (count)` or `const foo:string = someVariable ? 'a' : 'b'`. Instead, inspect for the null, undefined, or zero rather than letting the value be interpreted as truthy for falsy. For example, use`if (count == null)` or `const foo:string = someVariable != null 'a' : 'b'` or `if (count > 0)`.
+- Specify types where not obvious, such as when declaring variables and arguments, and for function return types.
+- Use `@if {}` syntax rather than `*ngIf` syntax.
 
-Data models are defined in each of the 3 applications, and should stay in sync.
+# Code
 
-Localizations that a Community Checker user might see should be created or edited in src/SIL.XForge.Scripture/ClientApp/src/assets/i18n/checking_en.json. Only localizations that a Community Checker user will not see can be created or edited in src/SIL.XForge.Scripture/ClientApp/src/assets/i18n/non_checking_en.json.
-Even if something is a system-wide feature that isn't specific to community checking functionality, it should still be placed in checking_en.json if a community checking user would POSSIBLY see it.
+- All code that you write should be able to pass eslint linting tests for TypeScript, or csharpier for C#.
+- Don't merely write code for the local context, but make changes that are good overall considering the architecture of the application and structure of the files and classes.