Cline rules

1# Project Structure
2 
3This section provides an overview of the folder structure used in this project, designed to be modular, scalable, and easy to maintain.
4 
5We follow a feature-based and App Router-oriented architecture using Next.js 15. Each directory serves a clear purpose: separating concerns like UI, business logic, API routes, static content, and reusable types.
6 
7## features/
8 
9This directory organizes the app into logical features such as todo, sign, top, and admin. Each feature has subfolders for UI components, templates, and logic (e.g., hooks, contexts, DnD logic). This makes each feature self-contained and easy to scale.
10 
11## tests/
12 
13This directory contains a comprehensive testing environment using Vitest and modern testing frameworks. The test suite achieves 100% pass rate with high code coverage and follows feature-based organization that mirrors the main application structure. It includes unit tests with MSW (Mock Service Worker) for API mocking, integration tests using Docker and Firebase Emulator environment, and end-to-end tests with Playwright for complete user workflow validation.
14 
15## app/
16 
17This is where the actual routing and rendering logic resides, structured by Next.js App Router conventions. Grouped routes like (auth) or (admin) allow cleaner separation between different parts of the application without polluting the URL.
18 
19## api/
20 
21All server functions (APIs) live here, further divided into general, admin, and auth routes. This separation ensures better access control and clearer codebase navigation.
22 
23## types/, data/, public/
24 
25These directories store cross-cutting concerns such as reusable types, static data (e.g., form definitions or validation rules), and assets like images or CSS. They help in maintaining clarity across the project by centralizing shared resources.
26 
27## todoApp-submodule/
28 
29The todoApp-submodule is a support module designed to centralize mock API management and documentation, improving development efficiency and team collaboration. It is primarily composed of the following two directories:
30 
31### mocks/
32 
33This directory centralizes mock API definitions using MSW (Mock Service Worker). It includes environment-specific setup files like browser.ts and server.ts, mock data such as todos.ts and user.ts, and API handlers like auth.ts and lists.ts. This structure enables frontend development to proceed independently, even when the backend is not yet implemented.
34 
35### docs/
36 
37This directory organizes the project's specifications and technical documents in a structured manner. Documentation is categorized by API, mock, and feature scope, including files such as MOCK.md and api/auth.md. Closely integrated with todoApp-submodule, it serves as a centralized knowledge base that supports design consistency and effective team communication.
38 
39```
40todoApp-next/
41├── app/                        # App Router-based route definitions for Next.js
42│   ├── (admin)/                # Grouped routes related to admin
43│   │   └── admin/              # Admin page
44│   │       └── page.tsx
45│   ├── (auth)/                 # Grouped routes related to authentication
46│   │   ├── _signIn/            # Logic for signing in
47│   │   │   └── signIn.ts
48│   │   ├── _signOut/           # Logic for signing out
49│   │   │   └── signOut.ts
50│   │   ├── _signUp/            # Logic for signing up
51│   │   │   └── signUp.ts
52│   │   ├── account/            # Account-related pages
53│   │   │   └── error/          # Account error page
54│   │   │       └── page.tsx
55│   │   ├── signin/             # Sign-in page
56│   │   │   └── page.tsx
57│   │   └── signup/             # Sign-up page
58│   │       └── page.tsx
59│   ├── (dashboards)/           # Grouped routes for dashboards
60│   │   ├── loading.tsx         # Loading screen for dashboard
61│   │   └── todo/               # Task management page
62│   │       └── page.tsx
63│   ├── api/                    # API routes
64│   │   ├── (admin)/            # Admin API
65│   │   │   └── users/          # Admin user API
66│   │   │       ├── [userId]/   # API for specific user
67│   │   │       │   ├── lists/  # List management API for a user
68│   │   │       │   │   └── route.ts
69│   │   │       │   └── todos/  # Todo management API for a user
70│   │   │       │       └── route.ts
71│   │   │       └── route.ts
72│   │   ├── (general)/          # General user API
73│   │   │   ├── dashboards/     # Content information API
74│   │   │   │   └── route.ts
75│   │   │   ├── lists/          # List management API
76│   │   │   │   └── route.ts
77│   │   │   ├── todos/          # Todo management API
78│   │   │   │   └── route.ts
79│   │   │   └── user/           # User info API
80│   │   │       └── route.ts
81│   │   ├── auth/               # Authentication-related APIs
82│   │   │   ├── [...nextauth]/  # NextAuth.js API handler
83│   │   │   ├── refresh/        # Token refresh API
84│   │   │   │   └── route.ts
85│   │   │   └── server-login/   # Server-side login API
86│   │   │       └── route.ts
87│   ├── libs/                   # Shared libraries
88│   ├── providers/              # React providers
89│   │   ├── MSWProvider.tsx     # Mock Service Worker provider
90│   │   └── SessionProvider.tsx # Session management provider
91│   ├── static/                 # Static CSS files
92│   │   ├── input.css
93│   │   └── output.css
94│   └── utils/                  # Utility functions
95├── features/                   # Feature-specific components and logic
96│   ├── admin/                  # Admin-related features
97│   │   ├── components/         # Admin UI components
98│   │   └── templates/          # Admin UI templates
99│   ├── libs/                   # Shared libraries
100│   ├── shared/                 # Shared features across the app
101│   │   ├── components/         # Common UI components
102│   │   │   └── elements/       # Generic UI elements
103│   │   └── templates/          # Shared templates
104│   ├── sign/                   # Sign-in/Sign-up features
105│   │   ├── components/         # Auth-related UI components
106│   │   │   └── elements/       # Auth-specific UI elements
107│   │   └── templates/          # Auth templates
108│   ├── todo/                   # Todo feature
109│   │   ├── components/         # UI components for todos
110│   │   │   └── elements/       # UI elements for todos
111│   │   ├── contexts/           # Context for todo state
112│   │   ├── dnd/                # Drag-and-drop logic
113│   │   ├── hooks/              # Custom hooks for todo
114│   │   └── templates/          # Todo page templates
115│   ├── top/                    # Top page feature
116│   │   ├── components/         # Top page UI components
117│   │   └── templates/          # Top page templates
118│   └── utils/                  # Shared utilities across features
119├── data/                       # Static data and link definitions
120│   ├── form.ts                 # Form definitions
121│   ├── validatedData.ts        # Validated data
122│   └── links/                  # External link definitions
123├── public/                     # Static assets such as images
124├── scripts/                    # Project utility scripts
125│   ├── init-firebase-data.ts   # Firebase Emulator data initialization (tsx execution)
126│   ├── cleanup-db.ts           # Test database cleanup
127│   └── helpers/                # Helper functions for scripts
128│       └── testDbDataFetcher.ts # Test data fetching utilities
129├── tests/                      # Comprehensive testing suite
130│   ├── setup.ts                # Global unit test environment setup
131│   ├── setup-integration.ts    # Integration test environment setup
132│   ├── test-utils.tsx          # Custom render functions and test utilities
133│   ├── features/               # Feature-based test structure
134│   │   ├── utils/              # Utility function tests (4 files)
135│   │   ├── shared/             # Shared component tests
136│   │   │   └── components/     # Navigation and common component tests
137│   │   ├── todo/               # Todo feature comprehensive testing
138│   │   │   ├── api.integration.test.ts    # Todo API integration tests
139│   │   │   ├── contexts/                  # TodoContext tests
140│   │   │   ├── components/                # Todo component tests (13 files)
141│   │   │   │   ├── elements/              # UI element tests (Status, TodoList, Add, Modal, Error)
142│   │   │   │   ├── PushContainer/         # Container component tests
143│   │   │   │   └── MainContainer/         # Main container tests
144│   │   │   ├── hooks/                     # Todo custom hooks tests (4 files)
145│   │   │   └── templates/                 # TodoWrapper template tests
146│   │   └── libs/               # Common library tests
147│   ├── e2e/                    # End-to-end testing with Playwright
148│   │   ├── global-setup.ts     # E2E test global setup
149│   │   ├── global-teardown.ts  # E2E test global cleanup
150│   │   └── todo-flow.spec.ts   # Comprehensive todo workflow E2E tests
151│   └── fixtures/               # Test fixtures for Firebase Emulator
152│       ├── auth_export/        # Authentication data export
153│       └── firestore_export/   # Firestore data export
154├── todoApp-submodule/
155│   ├── mocks/                 # Form definitions
156│   │   ├── browser.ts              # MSW browser configuration
157│   │   ├── server.ts               # MSW Node.js configuration
158│   │   ├── initMocks.ts            # Mock initialization
159│   │   ├── data/                   # Mock data definitions
160│   │   │   ├── index.ts            # Data exports
161│   │   │   ├── lists.ts            # List mock data
162│   │   │   ├── todos.ts            # Todo mock data
163│   │   │   └── user.ts             # User mock data
164│   │   └── handlers/               # API handler definitions
165│   │       ├── index.ts            # Handler exports
166│   │       ├── auth.ts             # Authentication API handlers
167│   │       ├── dashboard.ts        # Dashboard API handlers
168│   │       ├── lists.ts            # List API handlers
169│   │       └── todos.ts            # Todo API handlers
170│   └──  docs/                      # It contains project-wide documentation such as API specifications, feature overviews, and mock API details.
171│
172└── types/                      # TypeScript type definitions
173    ├── common.ts               # Common types
174    ├── components.ts           # Component-related types
175    ├── lists.ts                # List-related types
176    ├── next-auth.d.ts          # Types for NextAuth.js
177    ├── todos.ts                # Todo-related types
178    ├── auth/                   # Auth-specific types
179    ├── form/                   # Form-specific types
180    └── markdown/               # Markdown-related types
181```
182