zaid.marzguioui/myeasycms-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: consolidate AGENTS.md and CLAUDE.md files, update tech stac… (#444)

Browse Source 
* refactor: consolidate AGENTS.md and CLAUDE.md files, update tech stack and architecture details

- Merged content from CLAUDE.md into AGENTS.md for better organization.
- Updated tech stack section to reflect the current technologies used, including Next.js, Supabase, and Tailwind CSS.
- Enhanced monorepo structure documentation with detailed directory purposes.
- Streamlined multi-tenant architecture explanation and essential commands.
- Added key patterns for naming conventions and server actions.
- Removed outdated agent files related to Playwright and PostgreSQL, ensuring a cleaner codebase.
- Bumped version to 2.23.7 to reflect changes.
This commit is contained in:
Giancarlo Buomprisco
2026-01-18 10:44:40 +01:00
committed by GitHub
parent bebd56238b
commit cfa137795b
61 changed files with 3636 additions and 9522 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
apps/web/app/admin/AGENTS.md
View File

@@ -1,119 +1,55 @@
# Super Admin
This file provides specific guidance for AI agents working in the super admin section of the application.
## Critical Security Rules
## Core Admin Principles
- **ALWAYS** use `AdminGuard` to protect pages
- **ALWAYS** validate admin status before operations
- **NEVER** bypass authentication or authorization
- **ALWAYS** audit admin operations with logging
### Security-First Development
## Page Structure
- **ALWAYS** use `AdminGuard` to protect admin pages
- **NEVER** bypass authentication or authorization checks
- **CRITICAL**: Use admin Supabase client with manual authorization validation
- Validate permissions for every admin operation
```typescript
import { AdminGuard } from '@kit/admin/components/admin-guard';
import { PageBody, PageHeader } from '@kit/ui/page';
### Admin Client Usage Pattern
async function AdminPage() {
return (
<>
<PageHeader title="Admin" />
<PageBody>{/* Content */}</PageBody>
</>
);
}
export default AdminGuard(AdminPage);
```
## Admin Client Usage
```typescript
import { isSuperAdmin } from '@kit/admin';
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';
async function adminOperation() {
const adminClient = getSupabaseServerAdminClient();
// CRITICAL: Always validate admin status first
const currentUser = await getCurrentUser();
// CRITICAL: Validate first - admin client bypasses RLS
if (!(await isSuperAdmin(currentUser))) {
throw new Error('Unauthorized: Admin access required');
throw new Error('Unauthorized');
}
// Now safe to proceed with admin privileges
const { data } = await adminClient.from('accounts').select('*');
return data;
const adminClient = getSupabaseServerAdminClient();
// Safe to proceed
}
```
## Page Structure Patterns
### Standard Admin Page Template
## Audit Logging
```typescript
import { AdminGuard } from '@kit/admin/components/admin-guard';
import { PageBody, PageHeader } from '@kit/ui/page';
import { AppBreadcrumbs } from '@kit/ui/app-breadcrumbs';
async function AdminPageComponent() {
return (
<>
<PageHeader description={<AppBreadcrumbs />}>
{/* Page actions go here */}
</PageHeader>
<PageBody>
{/* Main content */}
</PageBody>
</>
);
}
// ALWAYS wrap with AdminGuard
export default AdminGuard(AdminPageComponent);
const logger = await getLogger();
logger.info({
name: 'admin-audit',
action: 'delete-user',
adminId: currentUser.id,
targetId: userId,
}, 'Admin action performed');
```
### Async Server Component Pattern
```typescript
// ✅ CORRECT - Next.js 16 pattern
async function AdminPage({ params }: { params: Promise<{ id: string }> }) {
const { id } = await params; // ✅ await params directly
// Fetch admin data
const data = await loadAdminData(id);
return <AdminContent data={data} />;
}
```
## Security Guidelines
### Critical Security Rules
1. **NEVER** expose admin functionality to non-admin users
2. **ALWAYS** validate admin status before operations
3. **NEVER** trust client-side admin checks alone
4. **ALWAYS** use server-side validation for admin actions
5. **NEVER** log sensitive admin data
6. **ALWAYS** audit admin operations
### Admin Action Auditing
```typescript
async function auditedAdminAction(action: string, data: unknown) {
const logger = await getLogger();
await logger.info(
{
name: 'admin-audit',
action,
adminId: currentUser.id,
timestamp: new Date().toISOString(),
data: {
// Log only non-sensitive fields
operation: action,
targetId: data.id,
},
},
'Admin action performed',
);
}
```
## Common Patterns to Follow
1. **Always wrap admin pages with `AdminGuard`**
2. **Use admin client only when RLS bypass is required**
3. **Implement proper error boundaries for admin components**
4. **Add comprehensive logging for admin operations**
5. **Use TypeScript strictly for admin interfaces**
6. **Follow the established admin component naming conventions**
7. **Implement proper loading states for admin operations**
8. **Add proper metadata to admin pages**

120
apps/web/app/admin/CLAUDE.md
View File

@@ -1,119 +1 @@
# Super Admin
This file provides specific guidance for AI agents working in the super admin section of the application.
## Core Admin Principles
### Security-First Development
- **ALWAYS** use `AdminGuard` to protect admin pages
- **NEVER** bypass authentication or authorization checks
- **CRITICAL**: Use admin Supabase client with manual authorization validation
- Validate permissions for every admin operation
### Admin Client Usage Pattern
```typescript
import { isSuperAdmin } from '@kit/admin';
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';
async function adminOperation() {
const adminClient = getSupabaseServerAdminClient();
// CRITICAL: Always validate admin status first
const currentUser = await getCurrentUser();
if (!(await isSuperAdmin(currentUser))) {
throw new Error('Unauthorized: Admin access required');
}
// Now safe to proceed with admin privileges
const { data } = await adminClient.from('accounts').select('*');
return data;
}
```
## Page Structure Patterns
### Standard Admin Page Template
```typescript
import { AdminGuard } from '@kit/admin/components/admin-guard';
import { PageBody, PageHeader } from '@kit/ui/page';
import { AppBreadcrumbs } from '@kit/ui/app-breadcrumbs';
async function AdminPageComponent() {
return (
<>
<PageHeader description={<AppBreadcrumbs />}>
{/* Page actions go here */}
</PageHeader>
<PageBody>
{/* Main content */}
</PageBody>
</>
);
}
// ALWAYS wrap with AdminGuard
export default AdminGuard(AdminPageComponent);
```
### Async Server Component Pattern
```typescript
// ✅ CORRECT - Next.js 16 pattern
async function AdminPage({ params }: { params: Promise<{ id: string }> }) {
const { id } = await params; // ✅ await params directly
// Fetch admin data
const data = await loadAdminData(id);
return <AdminContent data={data} />;
}
```
## Security Guidelines
### Critical Security Rules
1. **NEVER** expose admin functionality to non-admin users
2. **ALWAYS** validate admin status before operations
3. **NEVER** trust client-side admin checks alone
4. **ALWAYS** use server-side validation for admin actions
5. **NEVER** log sensitive admin data
6. **ALWAYS** audit admin operations
### Admin Action Auditing
```typescript
async function auditedAdminAction(action: string, data: unknown) {
const logger = await getLogger();
await logger.info(
{
name: 'admin-audit',
action,
adminId: currentUser.id,
timestamp: new Date().toISOString(),
data: {
// Log only non-sensitive fields
operation: action,
targetId: data.id,
},
},
'Admin action performed',
);
}
```
## Common Patterns to Follow
1. **Always wrap admin pages with `AdminGuard`**
2. **Use admin client only when RLS bypass is required**
3. **Implement proper error boundaries for admin components**
4. **Add comprehensive logging for admin operations**
5. **Use TypeScript strictly for admin interfaces**
6. **Follow the established admin component naming conventions**
7. **Implement proper loading states for admin operations**
8. **Add proper metadata to admin pages**
@AGENTS.md