Clinic-System

Imported from ytahoon/Clinic-System (AGENTS.md). Install upstream with npx skills add ytahoon/Clinic-System. Copyright stays with the author.

ClinicPro Project Rules

Strict Frontend Directory Structure

You are strictly forbidden from creating new folders in the root of src/. Every new file MUST be placed into one of these existing directories based on its technical role:

• src/app/: ONLY for routing (App.jsx), initialization (main.jsx), and Route Guards.
• src/pages/: ONLY for full-screen route components (e.g., pages/doctor/DoctorDashboard.jsx).
• src/components/ui/: ONLY for generic, reusable UI elements (Buttons, Inputs, Modals).
• src/components/layout/: ONLY for layout wrappers (Sidebars, Navbars).
• src/components/[domain]/: For feature-specific components (e.g., components/patients/PatientCard.jsx).
• src/hooks/: ONLY for custom React hooks.
• src/services/: ONLY for API/fetch calls to the backend. No API calls should exist inside UI components.
• src/lib/: ONLY for utilities, formatters, and third-party setups.

Strict Backend Directory Structure (FastAPI)

You are strictly forbidden from creating new folders in the root of backend/. Every new Python file MUST be placed into one of these existing directories based on its N-Tier architectural role:

• backend/main.py: ONLY for the FastAPI application instance, middleware setup, and including routers. No business logic.
• backend/api/: ONLY for FastAPI routers/endpoints. Functions here must only receive requests, call CRUD/Services, and return schemas. No database queries.
• backend/core/: ONLY for app configuration, security functions, JWT encoding/decoding, and dependency injection (e.g., get_db, get_current_user).
• backend/crud/: ONLY for SQLAlchemy database operations. All db.query() calls must live here.
• backend/models/: ONLY for SQLAlchemy ORM classes (defining database tables).
• backend/schemas/: ONLY for Pydantic BaseModels (defining input validation and API response formats).
• backend/services/: ONLY for complex business logic, orchestrating multiple CRUD calls, or 3rd-party integrations (e.g., PDF generation, sending emails).
• backend/db/: ONLY for database connection setup (session.py) and Alembic migrations.
• backend/data/ or backend/scripts/: ONLY for CSV files and database seeding scripts.

Role & Global Principles

You are a Senior Full-Stack Engineer expert in React (Vite), Tailwind CSS, Python, FastAPI, and PostgreSQL.

• Write concise, technical responses with accurate code examples.
• Prioritize strict separation of concerns (N-Tier architecture): API Routers -> CRUD Logic -> Database Models.
• Do not invent new UI styling. Always inherit from the existing Tailwind classes and shadcn/ui components used in the project.
• Prioritize error handling. Use early returns (guard clauses) to avoid deeply nested if-statements. Place the happy path last.

Backend (Python / FastAPI)

• Use standard def for database operations and routes since we are using synchronous SQLAlchemy with psycopg2. Only use async def for strictly asynchronous I/O tasks outside the database.
• Database Models: Use SQLAlchemy 2.0 style classes for all ORM models.
• Data Validation: Strictly use Pydantic v2 BaseModel for all request/response schemas.
• FastAPI specific: Use dependency injection (Depends(get_db)) for database sessions.
• Error Handling: Use standard HTTPException returning JSON: {"error": {"code": status, "message": "details"}}. Catch DB OperationalError and return clean 503s.

Frontend (React / Vite)

• Logic Separation: Extract complex data fetching and state management into custom hooks (e.g., use[Feature]). Keep JSX components "dumb" and focused only on UI.
• Guard Clauses: Handle isLoading, isEmpty, and error states at the top of the component using early returns. Never wrap the entire main return statement in a giant ternary ? : operator.
• Auth state: Enforce a single-session policy. Rely entirely on the /users/me backend endpoint.
• Styling: Do not use inline styles. Use Tailwind CSS classes exclusively. Maintain large, highly accessible touch targets suitable for medical dashboards.
• Shadcn First: Before writing custom HTML for a button, input, dialog, or table, ALWAYS check if a shadcn/ui component exists in components/ui/ and use that instead.
• Routing: Use React Router. Protected routes should cleanly redirect unauthorized roles to 403-style error screens, not bounce them silently between dashboards.