-
Notifications
You must be signed in to change notification settings - Fork 4
[AC-532] Updates to the PRD-4.1 Document #265
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
stephenfuqua
wants to merge
14
commits into
main
Choose a base branch
from
PRD-4.1-updates
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
19b3013
docs(prd): sync ODS instance management section with PR #263
stephenfuqua 94f9518
docs(prd): add ODS instance status/list and delete requirements from …
stephenfuqua f2d6523
docs: Provide more information about minimal and populated template f…
stephenfuqua fd4ec19
chore: Update to ODS/API 7.3.2
stephenfuqua b56bcf0
fix: Correction - Ed-Fi Admin App does _not_ support ODS database man…
stephenfuqua 8ed0971
docs: Update ODS Instance Management, reflecting that this capability…
stephenfuqua bee17ca
doc: Replace "Admin API" with "Management API" and "ODS Instance" wit…
stephenfuqua 4b94bc8
chore: Update v3 docker template to match v2 docker template
stephenfuqua 5a9b54a
chore: Rename file
stephenfuqua d04cb0e
docs: Correct CLAUDE.md inaccuracies and fill gaps
stephenfuqua bc5acda
chore: Remove unused Cypress dependencies
stephenfuqua b9ca2a6
docs: Clarifications based on code review
stephenfuqua b045129
fix: Resolve Copilot review comments
stephenfuqua c8adeb5
fix: Pin @babel/* dev deps to 7.x to restore Nx test compatibility
stephenfuqua File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,156 +1 @@ | ||
| # Admin App - Coding Agent Instructions | ||
|
|
||
| ## Overview | ||
|
|
||
| The Admin App is a centralized management system for Ed-Fi Technology Suite deployments. It provides a unified interface for managing multiple Ed-Fi API instances across on-premises, cloud, or Starting Blocks environments. | ||
|
|
||
| ## Project Structure | ||
|
|
||
| ```none | ||
| packages/ | ||
| ├── api/ # NestJS backend application | ||
| ├── fe/ # React frontend application | ||
| ├── common-ui/ # Shared UI components with Storybook | ||
| ├── models/ # Shared TypeScript models/types | ||
| ├── models-server/ # Server-side specific models | ||
| └── utils/ # Shared utilities | ||
| ``` | ||
|
|
||
| ## Key Technologies & Dependencies | ||
|
|
||
| ### Frontend Stack | ||
|
|
||
| - **React** with TypeScript | ||
| - **Chakra UI** for component library | ||
| - **Vite** for build tooling | ||
| - **TanStack Query** for data fetching | ||
| - **React Router DOM** for routing | ||
| - **React Hook Form** for form management | ||
| - **Jotai** for state management | ||
|
|
||
| ### Backend Stack | ||
|
|
||
| - **NestJS** framework | ||
| - **TypeORM** for database ORM | ||
| - **PostgreSQL** as primary database, or alternatively **Microsoft SQL Server** | ||
| - **Express Session** for session management | ||
| - **Passport** for authentication | ||
|
|
||
| ### Development Tools | ||
|
|
||
| - **Nx** for monorepo management | ||
| - **ESLint** with TypeScript support | ||
| - **Prettier** for code formatting | ||
| - **Jest** for testing | ||
| - **Storybook** for component development | ||
|
|
||
| ### Key Commands | ||
|
|
||
| - `npm run build:fe` - Build frontend | ||
| - `npm run build:api` - Build API | ||
| - `npm run migrations:generate -- MigrationName` - Generate database migration | ||
| - `npm run migrations:run` - Run pending migrations | ||
| - `npm run test:api` - Run API tests | ||
| - `npm run test:fe` - Run frontend tests | ||
| - `npm run lint:check` - Check linting | ||
| - `npm run storybook` - Start Storybook | ||
|
|
||
| ## Development Guidelines | ||
|
|
||
| ### Code Organization | ||
|
|
||
| - **Monorepo**: Use Nx workspace structure with clear package boundaries | ||
| - **Shared Code**: Common utilities in `utils/`, UI components in `common-ui/` | ||
| - **Models**: Separate client (`models/`) and server (`models-server/`) models | ||
| - **TypeScript**: Strict typing throughout the codebase | ||
|
|
||
| ### Database Management | ||
|
|
||
| - **Migrations**: Always generate migrations for schema changes | ||
| - **TypeORM**: Use decorators and entities for database modeling | ||
| - **Multiple DBs**: Support for both PostgreSQL and MSSQL | ||
|
|
||
| ### Authentication & Security | ||
|
|
||
| - **OIDC Integration**: Configurable identity providers | ||
| - **Session Management**: Express sessions with database storage | ||
| - **Machine Users**: Support for M2M authentication via OAuth | ||
| - **Encryption**: Sensitive data encrypted at rest | ||
|
|
||
| ### Testing Strategy | ||
|
|
||
| - **Unit Tests**: Jest for both frontend and backend | ||
| - **E2E Tests**: Cypress for integration testing | ||
| - **Storybook**: Component testing and documentation | ||
| - **Test Coverage**: Maintain good coverage across packages | ||
|
|
||
| ### Code Quality | ||
|
|
||
| - **REQUIRED**: Obey the `.editorconfig` file settings at all times. The project uses: | ||
| - UTF-8 character encoding | ||
| - LF line endings | ||
| - 2-space indentation | ||
| - Spaces for indentation style | ||
| - Final newlines required | ||
| - Trailing whitespace must be trimmed | ||
| - **ESLint**: Enforce coding standards with TypeScript rules | ||
| - **Prettier**: Consistent code formatting | ||
| - **Semantic Release**: Automated versioning based on commit messages | ||
| - **PR Guidelines**: Use semantic commit messages (feat:, fix:, docs:, etc.) | ||
| - **REQUIRED**: Execute `npm run build` before submitting any changes and correct any build errors | ||
|
|
||
| ## Common Development Tasks | ||
|
|
||
| ### Adding New Features | ||
|
|
||
| 1. **Plan**: Break down into smaller concepts | ||
| 2. **Models**: Define TypeScript interfaces in appropriate packages | ||
| 3. **Database**: Create migrations if schema changes needed | ||
| 4. **Backend**: Implement NestJS controllers, services, DTOs | ||
| 5. **Frontend**: Create React components, hooks, and pages | ||
| 6. **Tests**: Add unit and integration tests | ||
| 7. **Documentation**: Update relevant docs | ||
|
|
||
| ### Working with Database | ||
|
|
||
| ```bash | ||
| # Generate migration | ||
| npm run migrations:generate -- AddNewFeature | ||
|
|
||
| # Run migrations on PostgreSQL | ||
| npm run migrations:run | ||
|
|
||
| # Revert last migration | ||
| npm run migrations:revert | ||
| ``` | ||
|
|
||
| ### Component Development | ||
|
|
||
| ```bash | ||
| # Start Storybook | ||
| npm run storybook | ||
|
|
||
| # Build Storybook | ||
| npm run build-storybook:common-ui | ||
| ``` | ||
|
|
||
| ## Contributing | ||
|
|
||
| ### Commit Message Format | ||
|
|
||
| Use semantic commit messages for automated versioning: | ||
|
|
||
| - `feature:` - New features (minor version bump) | ||
| - `fix:` - Bug fixes (patch version bump) | ||
| - `docs:` - Documentation updates (no version bump) | ||
| - `refactor:` - Code improvements (patch version bump) | ||
| - `test:` - Test updates (no version bump) | ||
| - `chore:` - Maintenance tasks (no version bump) | ||
|
|
||
| ### Pull Request Process | ||
|
|
||
| 1. Create feature branch from `main` | ||
| 2. Use semantic commit messages | ||
| 3. Include unit tests for new functionality | ||
| 4. Update documentation as needed | ||
| 5. Ensure all checks pass | ||
| Read @CLAUDE.md |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,161 @@ | ||
| # Admin App - Coding Agent Instructions | ||
|
|
||
| ## Overview | ||
|
|
||
| The Admin App is a centralized management system for Ed-Fi Technology Suite deployments. It provides a unified interface for managing multiple Ed-Fi API instances across on-premises, cloud, or Starting Blocks environments. | ||
|
|
||
| ## Project Structure | ||
|
|
||
| ```none | ||
| packages/ | ||
| ├── api/ # NestJS backend application | ||
| ├── fe/ # React frontend application | ||
| ├── common-ui/ # Shared UI components with Storybook | ||
| ├── models/ # Shared TypeScript models/types | ||
| ├── models-server/ # Server-side specific models | ||
| └── utils/ # Shared utilities | ||
| ``` | ||
|
|
||
| ## Key Technologies & Dependencies | ||
|
|
||
| ### Frontend Stack | ||
|
|
||
| - **React** with TypeScript | ||
| - **Chakra UI** for component library | ||
| - **Vite** for build tooling | ||
| - **TanStack Query** for data fetching | ||
| - **React Router DOM** for routing | ||
| - **React Hook Form** for form management | ||
| - **Jotai** for state management | ||
|
|
||
| ### Backend Stack | ||
|
|
||
| - **NestJS** framework | ||
| - **TypeORM** for database ORM | ||
| - **PostgreSQL** as primary database, or alternatively **Microsoft SQL Server** | ||
| - **Express Session** for session management | ||
| - **Passport** for authentication | ||
|
|
||
| ### Development Tools | ||
|
|
||
| - **Nx** for monorepo management | ||
| - **ESLint** with TypeScript support | ||
| - **Prettier** for code formatting | ||
| - **Jest** for testing | ||
| - **Storybook** for component development | ||
| - **Node.js >=24.0.0** required (see `.nvmrc` for the exact pinned version) | ||
|
|
||
| ### Key Commands | ||
|
|
||
| - `npm run build:fe` - Build frontend | ||
| - `npm run build:api` - Build API | ||
| - `npm run migrations:generate -- MigrationName` - Generate database migration | ||
| - `npm run migrations:run` - Run pending migrations | ||
| - `npm run migrations:run:mssql` - Run pending migrations against MSSQL | ||
| - `npm run test:api` - Run API tests | ||
| - `npm run test:fe` - Run frontend tests | ||
| - `npm run test:e2e:bdd` - Run Playwright/Gherkin E2E tests | ||
| - `npm run lint:check` - Check linting | ||
| - `npm run storybook` - Start Storybook | ||
|
|
||
| ## Development Guidelines | ||
|
|
||
| ### Code Organization | ||
|
|
||
| - **Monorepo**: Use Nx workspace structure with clear package boundaries | ||
| - **Shared Code**: Common utilities in `utils/`, UI components in `common-ui/` | ||
| - **Models**: Separate client (`models/`) and server (`models-server/`) models | ||
| - **TypeScript**: Strict typing throughout the codebase | ||
|
|
||
| ### Database Management | ||
|
|
||
| - **Migrations**: Always generate migrations for schema changes | ||
| - **TypeORM**: Use decorators and entities for database modeling | ||
| - **Multiple DBs**: Support for both PostgreSQL and MSSQL | ||
|
|
||
| ### Authentication & Security | ||
|
|
||
| - **OIDC Integration**: Configurable identity providers | ||
| - **Session Management**: Express sessions with database storage | ||
| - **Machine Users**: Support for M2M authentication via OAuth | ||
| - **Encryption**: Sensitive data encrypted at rest | ||
|
|
||
| ### Testing Strategy | ||
|
|
||
| - **Unit Tests**: Jest for both frontend and backend | ||
| - **E2E Tests**: Playwright with Gherkin/BDD feature files (`tests/e2e/**/*.feature`) | ||
| - **Storybook**: Component testing and documentation | ||
| - **Test Coverage**: Maintain good coverage across packages | ||
|
|
||
| ### Code Quality | ||
|
|
||
| - **REQUIRED**: Obey the `.editorconfig` file settings at all times. The project uses: | ||
| - UTF-8 character encoding | ||
| - 2-space indentation | ||
| - Spaces for indentation style | ||
| - Final newlines required | ||
| - Trailing whitespace must be trimmed | ||
| - **REQUIRED**: LF line endings are enforced repo-wide via `.gitattributes` (`* text=auto eol=lf`) | ||
| - **ESLint**: Enforce coding standards with TypeScript rules | ||
| - **Prettier**: Consistent code formatting | ||
| - **Semantic Release**: Automated versioning based on commit messages | ||
| - **PR Guidelines**: Use semantic commit messages (feat:, fix:, docs:, etc.) | ||
| - **REQUIRED**: Execute `npm run build` before submitting any changes and correct any build errors | ||
|
|
||
| ## Common Development Tasks | ||
|
|
||
| ### Adding New Features | ||
|
|
||
| 1. **Plan**: Break down into smaller concepts | ||
| 2. **Models**: Define TypeScript interfaces in appropriate packages | ||
| 3. **Database**: Create migrations if schema changes needed | ||
| 4. **Backend**: Implement NestJS controllers, services, DTOs | ||
| 5. **Frontend**: Create React components, hooks, and pages | ||
| 6. **Tests**: Add unit and integration tests | ||
| 7. **Documentation**: Update relevant docs | ||
|
|
||
| ### Working with Database | ||
|
|
||
| ```bash | ||
| # Generate migration | ||
| npm run migrations:generate -- AddNewFeature | ||
|
|
||
| # Run migrations on PostgreSQL | ||
| npm run migrations:run | ||
|
|
||
| # Revert last migration | ||
| npm run migrations:revert | ||
| ``` | ||
|
|
||
| ### Component Development | ||
|
|
||
| ```bash | ||
| # Start Storybook | ||
| npm run storybook | ||
|
|
||
| # Build Storybook | ||
| npm run build-storybook:common-ui | ||
| ``` | ||
|
|
||
| ## Contributing | ||
|
|
||
| ### Commit Message Format | ||
|
|
||
| Use semantic commit messages for automated versioning (see `release.config.mjs`): | ||
|
|
||
| - `feat:` / `feature:` - New features (minor version bump) | ||
| - `fix:` - Bug fixes (patch version bump) | ||
| - `docs:` - Documentation updates (no version bump) | ||
| - `refactor:` - Code improvements (patch version bump) | ||
| - `perf:` / `performance:` - Performance improvements (patch version bump) | ||
| - `test:` - Test updates (no version bump) | ||
| - `chore:` - Maintenance tasks (no version bump) | ||
| - `build:` / `ci:` - Build system or CI changes (no version bump) | ||
|
|
||
| ### Pull Request Process | ||
|
|
||
| 1. Create feature branch from `main` | ||
| 2. Use semantic commit messages | ||
| 3. Include unit tests for new functionality | ||
| 4. Update documentation as needed | ||
| 5. Ensure all checks pass | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.