Welcome to the Sign2Text project! This document provides guidelines for future contributors, maintainers, and AI assistants to ensure the repository remains professional, secure, and maintainable.
- Select Fork on the original Sign2Text repository.
- Create a focused branch in your fork for the proposed improvement.
- Make and test your change. Keep existing copyright and contributor attribution intact.
- Open a pull request back to
kokoc30/Sign2Text-ASL-Englishwith a description of the change and the tests you ran. - Respond to review feedback. Changes are merged only at the maintainers' discretion.
Please do not upload excluded model weights, private datasets, credentials, or private team-owned modules. This is a source-available repository, not an open-source project. The limited permissions for non-commercial development and GitHub forks are in COPYRIGHT.md. Submitting a pull request does not guarantee acceptance.
Sign2Text is a multi-service, multi-surface application. Before making changes, you must understand that several independent surfaces are tightly coupled through a shared routing layer and configuration.
- Main App: Static files in
frontend/(entry pointindex.html). - Landing Site: React/Vite source in
landing/src(built tolanding/dist). - Admin Dashboard: Admin management at
frontend/admin.html. - Legal: Markdown sources in
docs/and standalone HTML infrontend/. - API Services: Four FastAPI services (
ASL,Voice,Letter,Admin) running on ports8000-8003. - Frontend Server: A custom routing layer in
backend/frontend_server.pythat unifies all these surfaces on port5500.
To work on this project locally, follow these established steps:
- Environment Setup: Use
.\setup.ps1to create and configure the Python virtual environment (.venv). - Launching: Use
.\start.ps1to boot the entire stack. This automatically generates aruntime-config.jsfor the frontend to discover the backend services. - Testing: Before submitting changes, run the automated test suite:
.\.venv\Scripts\python.exe -m pytest
- Verification: After any UI or routing change, verify that all three surfaces (App, Admin, Landing) remain accessible via the
frontend_server.pyrouting.
- Preserve Routing Behavior: Do not modify
backend/frontend_server.pyorbackend/runtime_config.pyunless the change is project-wide. Breaking these will break cross-service communication. - Mode Isolation: Keep the logic for ASL, Voice, and Letter modes separated. Avoid cross-pollinating their backend dependencies.
- Security Sensitivity:
- Protect
X-Admin-Tokenvalidation inadmin_server.py. - Ensure
OLLAMA_AUTH_TOKENand other secrets are never exposed to the frontend inruntime-config.js.
- Protect
- Single Source of Truth:
- Legal content is grounded in
docs/PRIVACY_POLICY.mdanddocs/TERMS_OF_USE.md. - Configuration defaults are grounded in
backend/runtime_config.py.
- Legal content is grounded in
- Repo-Grounded: Ensure all documentation reflects the actual current code. Avoid "vague" or "future" promises unless clearly marked as a roadmap item.
- Index Maintenance: When adding a new documentation file in
docs/, update the index in docs/README.md immediately. - Consistency: Keep paths and route names consistent with the architecture documented in
tech/ARCHITECTURE.md.
- Clear Scope: Avoid unrelated refactors. Submit one logical change per PR.
- Surface Impact: List which surfaces are affected (e.g., "Frontend App + Admin API").
- Verification Steps: Include the specific manual or automated steps taken to verify the change.
- Docs Check: Confirm that relevant documentation has been updated to reflect the new behavior or configuration.
Tip
If you are an AI assistant working on this repo, always read the documentation in docs/ before proposing structural changes. Respect the existing multi-service boundaries.