diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000..3bb2b4e0 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,157 @@ +# Shiksha Teachers App Architecture + +This document provides an overview of the Shiksha Teachers App architecture, explaining the key components, data flow, and design decisions. + +## Application Architecture + +Shiksha Teachers App is built using Next.js, a React framework that provides server-side rendering, static site generation, and API routes. The application follows a component-based architecture with state management via Zustand. + +### High-Level Architecture + +``` ++------------------+ +------------------+ +------------------+ +| | | | | | +| UI Components |<--->| State/Services |<--->| External APIs | +| | | | | | ++------------------+ +------------------+ +------------------+ +``` + +## Key Technologies + +- **Next.js**: React framework for rendering and routing +- **TypeScript**: For type safety across the application +- **Material UI**: Component library for UI elements +- **Zustand**: State management +- **Axios**: HTTP client for API requests +- **React Query**: Data fetching and caching +- **i18next**: Internationalization +- **Jest & React Testing Library**: Testing framework + +## Project Structure + +### Core Directories + +- **/src/components**: Reusable UI components +- **/src/pages**: Next.js pages and routing +- **/src/services**: API service layers +- **/src/utils**: Utility functions, helpers, and interfaces +- **/src/store**: State management +- **/src/hooks**: Custom React hooks +- **/src/styles**: Global styles and themes + +### Data Flow + +``` ++-----------------+ +----------------+ +----------------+ +| | | | | | +| User Interaction|---->| Component |---->| Service Layer | +| | | (React/State) | | (API Calls) | ++-----------------+ +----------------+ +----------------+ + | + v ++-----------------+ +----------------+ +----------------+ +| | | | | | +| UI Update |<----| State Update |<----| External API | +| | | | | | ++-----------------+ +----------------+ +----------------+ +``` + +## Key Components + +### Pages + +The `/src/pages` directory contains the main application pages, following Next.js conventions: + +- **_app.tsx**: Application entry point with global providers +- **dashboard.tsx**: Main dashboard with analytics +- **attendance-overview.tsx**: Overview of attendance statistics +- **course-planner.tsx**: Curriculum and course planning + +### Components + +The application uses a component-based architecture with reusable components: + +- **Form Components**: Input fields, selectors, and form utilities +- **Common Components**: Headers, loaders, modals +- **Specialized Components**: Attendance tracking, student cards, assessment reports + +## Data Management + +### State Management + +Zustand is used for global state management, with stores for: +- User authentication +- UI state (themes, modals) +- Attendance data +- Course planning + +### API Services + +The `/src/services` directory contains service modules for API interactions: +- Authentication services +- Attendance tracking +- Course planning +- User management + +## Authentication & Authorization + +The application uses token-based authentication, storing user tokens in local storage. Routes are protected using Higher Order Components (HOCs) that check for valid authentication before rendering protected pages. + +## Core Features Implementation + +### Attendance Tracking + +Attendance tracking is implemented with the following components: +- **MarkAttendance.tsx**: UI for marking individual attendance +- **MarkBulkAttendance.tsx**: Bulk attendance operations +- **AttendanceDetails.tsx**: Detailed attendance reports +- **AttendanceHistory.tsx**: Historical attendance data + +Data flow: +1. Teacher selects class/cohort +2. Attendance UI displays student list +3. Teacher marks attendance +4. Data is sent to API via service layer +5. UI updates to reflect changes + +### Course Planning + +Course planning features include: +- **CoursePlannerCards.tsx**: Visual display of course plans +- **TopicDetails.tsx**: Details for specific topics +- **CourseAccordion.tsx**: Expandable course content + +### User Management + +User management includes: +- **AddFacilitator.tsx**: Adding new teachers/facilitators +- **ManageUser.tsx**: User management interface +- **AddLearnerModal.tsx**: Adding new students + +## Performance Considerations + +- React Query is used for data fetching and caching to reduce API calls +- Component memoization for expensive renders +- Lazy loading for less critical components + +## Extensibility + +The application is designed to be extended: +- New components can be added to the component directories +- New pages follow Next.js conventions +- Services can be expanded for new API endpoints + +## Testing Strategy + +- Unit tests for utility functions +- Component tests for UI components +- Integration tests for component interactions +- End-to-end tests for critical flows + +## Future Architecture Considerations + +Areas for architectural improvement: +- Migration to Next.js App Router +- Enhanced state management with more granular stores +- Improved API error handling and retry mechanisms +- Micro-frontend architecture for larger scale \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..f6b3c6e8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,187 @@ +# Contributing to Shiksha Teachers App + +Thank you for considering contributing to the Shiksha Teachers App! This document outlines the process for contributing to the project and provides guidelines to make the contribution process smooth and effective. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) + - [Project Setup](#project-setup) + - [Development Environment](#development-environment) +- [How to Contribute](#how-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Pull Requests](#pull-requests) +- [Development Workflow](#development-workflow) + - [Branching Strategy](#branching-strategy) + - [Commit Guidelines](#commit-guidelines) + - [Code Style](#code-style) +- [Testing Guidelines](#testing-guidelines) +- [Documentation Guidelines](#documentation-guidelines) + +## Code of Conduct + +By participating in this project, you are expected to uphold our Code of Conduct. Please treat all community members with respect and create a positive environment for everyone. + +## Getting Started + +### Project Setup + +1. Fork the repository on GitHub +2. Clone your fork locally + ```bash + git clone https://github.com/YOUR_USERNAME/shiksha-frontend.git + cd shiksha-frontend + git checkout shiksha-2.0 + ``` +3. Add the original repository as an upstream remote + ```bash + git remote add upstream https://github.com/tekdi/shiksha-frontend.git + ``` +4. Install dependencies + ```bash + npm install + ``` +5. Set up environment variables following the instructions in the README + +### Development Environment + +Make sure your development environment meets the prerequisites listed in the README: +- Node.js ≥ 18.19.0 +- npm ≥ 10.2.3 + +## How to Contribute + +### Reporting Bugs + +Before reporting a bug, please check if it has already been reported by searching the existing issues. + +When reporting a bug, include: +1. A clear and descriptive title +2. Steps to reproduce the bug +3. Expected behavior +4. Actual behavior +5. Screenshots if applicable +6. Environment details (browser, OS, device) + +### Suggesting Enhancements + +We welcome suggestions for enhancements. When suggesting a feature: +1. Provide a clear description of the feature +2. Explain why this feature would be useful to most users +3. Provide examples of how this feature would work in practice + +### Pull Requests + +1. Create a new branch from the `shiksha-2.0` branch: + ```bash + git checkout -b feature/your-feature-name + ``` +2. Make your changes +3. Run the tests to ensure your changes don't break existing functionality + ```bash + npm test + ``` +4. Run linting checks + ```bash + npm run lint + ``` +5. Commit your changes following the [commit guidelines](#commit-guidelines) +6. Push to your fork + ```bash + git push origin feature/your-feature-name + ``` +7. Open a pull request against the `shiksha-2.0` branch of the original repository + +## Development Workflow + +### Branching Strategy + +- `shiksha-2.0`: The main development branch +- `feature/*`: For new features +- `bugfix/*`: For bug fixes +- `docs/*`: For documentation changes +- `refactor/*`: For code refactoring with no feature changes + +### Commit Guidelines + +- Use the present tense ("Add feature" not "Added feature") +- Use the imperative mood ("Move cursor to..." not "Moves cursor to...") +- Limit the first line to 72 characters or less +- Reference issues and pull requests in the commit message where appropriate +- Consider using a conventional commit format: + ``` + (): + + [optional body] + + [optional footer] + ``` + Types include: feat, fix, docs, style, refactor, test, chore + +### Code Style + +- Follow the existing code style in the project +- Use 2 spaces for indentation +- Use consistent naming conventions + - React components should use PascalCase (e.g., `StudentCard.tsx`) + - Utility functions should use camelCase (e.g., `formatDate.ts`) +- Add JSDoc comments to functions, especially those that are exported +- Follow TypeScript best practices, including: + - Use proper type annotations + - Avoid using `any` when possible + - Use interfaces for complex objects + +## Testing Guidelines + +- Write tests for all new features +- Maintain or improve code coverage with each PR +- Types of tests to include: + - Unit tests for utility functions and isolated components + - Integration tests for component interactions + - End-to-end tests for critical user flows + +### Writing Good Tests + +1. Test the behavior, not the implementation +2. Keep tests simple and focused +3. Use descriptive test names that explain the expected behavior +4. Set up test data in a way that makes tests easy to understand + +## Documentation Guidelines + +- Update documentation for any changes to APIs, components, or user flows +- Document complex functions with JSDoc comments +- Include examples for non-trivial components or functions +- Keep README and other documentation up to date + +### JSDoc Format + +Use the following format for JSDoc comments: + +```typescript +/** + * Brief description of what the function does + * + * @param {Type} paramName - Description of parameter + * @returns {ReturnType} Description of return value + * @example + * // Example usage + * const result = myFunction('example'); + */ +``` + +## Areas for Contribution + +Here are some specific areas where contributions are currently needed: + +1. **UI/UX Improvements**: Enhance the user interface and experience +2. **Performance Optimization**: Identify and fix performance bottlenecks +3. **Accessibility**: Improve the accessibility of the application +4. **Test Coverage**: Increase test coverage +5. **Documentation**: Improve and expand documentation +6. **Internationalization**: Add or improve translations + +## Thank You! + +Your contributions help make this project better for everyone. Thank you for your time and effort! \ No newline at end of file diff --git a/README.md b/README.md index cef4a3f4..6b248e6e 100644 --- a/README.md +++ b/README.md @@ -7,22 +7,70 @@ [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=tekdi_teachers-app&metric=bugs)](https://sonarcloud.io/summary/new_code?id=tekdi_teachers-app) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=tekdi_teachers-app&metric=coverage)](https://sonarcloud.io/summary/new_code?id=tekdi_teachers-app) -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). -# Shiksha: Teachers-application +# Shiksha: Teachers Application ## What is Shiksha? -Shiksha is a next-generation scalable open-source learning solution for teachers. - -## Getting Started - -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). - -## new changes - -### Prerequisites - - +Shiksha is a next-generation scalable open-source learning solution for teachers. It provides a comprehensive platform for teachers to manage classes, track attendance, assess student performance, and plan courses effectively. + +## Overview + +This application is built with Next.js and provides a robust suite of tools for educational management, including: + +- Dashboard for metrics and analytics +- Attendance tracking and reporting +- Course planning and curriculum management +- Student assessment and performance tracking +- User management for teachers, facilitators, and learners +- Center/school management + +## Tech Stack + +- **Frontend Framework**: Next.js (React) +- **State Management**: Zustand +- **UI Components**: Material UI +- **Form Handling**: React JSON Schema Form (RJSF) +- **Data Fetching**: Axios, React Query +- **Analytics**: Google Analytics, Telemetry SDK +- **Internationalization**: i18next +- **Testing**: Jest, Cypress + +## Project Structure + +``` +shiksha-teachers-app/ +├── src/ # Source code +│ ├── @types/ # TypeScript type definitions +│ ├── assets/ # Static assets (images, fonts) +│ ├── components/ # Reusable React components +│ │ ├── blocks/ # Composable block components +│ │ ├── center/ # Center/school related components +│ │ ├── common/ # Common utility components +│ │ └── form/ # Form-related components +│ ├── hooks/ # Custom React hooks +│ ├── pages/ # Next.js pages +│ │ ├── api/ # API routes +│ │ ├── assessments/ # Assessment-related pages +│ │ ├── centers/ # Center management pages +│ │ └── learner/ # Learner profile pages +│ ├── services/ # API service layers +│ ├── store/ # State management +│ ├── styles/ # Global styles and themes +│ └── utils/ # Utility functions and constants +│ └── hoc/ # Higher-order components +├── public/ # Public assets +├── types/ # Global TypeScript types +├── __tests__/ # Test files +├── cypress/ # End-to-end tests +├── jest.config.ts # Jest configuration +└── next.config.mjs # Next.js configuration +``` + +## Prerequisites + +### System Requirements + +
@@ -32,7 +80,7 @@ This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next - + @@ -40,40 +88,133 @@ This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next
System Requirements
RAM> >= 8 Gb≥ 8 GB
CPU
-| Software dependencies | | -| :------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | -| **[Node](https://nodejs.org/en/download/)** | > 18.19.0 (or Install the latest release of LTS version) | -| **[npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager)** | 10.2.3 | - -### Project Setup +### Software Dependencies -1. Clone project +| Software | Version | +| :------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| **[Node.js](https://nodejs.org/en/download/)** | ≥ 18.19.0 (or latest LTS version) | +| **[npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager)** | ≥ 10.2.3 | - ```console - git clone https://github.com/tekdi/shiksha-frontend/tree/shiksha-2.0 - ``` +## Getting Started - > **_Note_**: Stable versions of the sunbird portal are available via tags for each release, and the master branch contains latest stable release. For latest stable release [refer](https://github.com/Sunbird-Ed/SunbirdEd-portal/branches) +### Project Setup -2. Install required dependencies - ```console - npm install +1. Clone the repository + ```bash + git clone https://github.com/tekdi/shiksha-frontend.git + cd shiksha-frontend + git checkout shiksha-2.0 ``` -3. Configuring the Environment - Refer the sample environment file: https://github.com/tekdi/shiksha-frontend/blob/shiksha-2.0/.env-sample -### Running Application - -1. Run the application in development mode - - ```console - npm run dev +2. Install dependencies + ```bash + npm install ``` - Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +3. Set up environment variables + - Create a `.env.local` file in the root directory + - Use the `.env-sample` file as a reference + - Required environment variables: + ``` + NEXT_PUBLIC_BASE_URL= + NEXT_PUBLIC_TELEMETRY_URL= + NEXT_PUBLIC_MEASUREMENT_ID= + ``` + +### Running the Application + +#### Development Mode +```bash +npm run dev +``` +The application will be available at [http://localhost:3000](http://localhost:3000) + +#### Production Build +```bash +npm run build +npm start +``` + +### Testing + +#### Unit Tests +```bash +npm test # Run all tests +npm run test:watch # Run tests in watch mode +npm run test:coverage # Generate test coverage report +``` + +#### End-to-End Tests +```bash +npm run cypress:open # Open Cypress test runner +``` + +### Code Quality Tools + +```bash +npm run lint # Run ESLint +npm run lint:fix # Fix ESLint issues +npm run prettier # Format code with Prettier +npm run lint:css # Run stylelint for CSS/SCSS +npm run lint:css:fix # Fix stylelint issues +``` + +## Key Features + +### Dashboard +The dashboard provides an overview of key metrics including attendance statistics, course progress, and student performance. + +### Attendance Management +- Mark attendance for individual or multiple students +- View attendance history +- Generate attendance reports +- Track attendance patterns and identify low attendance students + +### Course Planning +- Create and manage course plans +- Track curriculum progress +- Organize topics and sessions + +### Assessment +- Create and manage assessments +- Track student performance +- Generate assessment reports + +### User Management +- Manage teachers, facilitators, and learners +- User authentication and authorization +- Role-based access control + +## Contributing + +We welcome contributions to improve Shiksha! Here's how you can contribute: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add some amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Code Conventions + +- Follow the existing code style and structure +- Write tests for new features +- Update documentation for any changes +- Use meaningful commit messages + +### Development Workflow + +1. Pick an issue from the issue tracker or create a new one +2. Discuss the approach in the issue +3. Implement the changes +4. Add tests and documentation +5. Submit a pull request + +## License + +This project is licensed under the [LICENSE_NAME] - see the LICENSE file for details. + +## Acknowledgments -2. To build the application use - ```console - npm run build - ``` -# +- The Sunbird ecosystem for providing foundation components +- All contributors who have helped make this project better