@@ -9,6 +9,7 @@ Syft Space Server is a full-stack application with a FastAPI backend and Vue 3 f
99## Architecture
1010
1111### Backend Structure (` /backend ` )
12+
1213- ** Framework** : FastAPI with FastSyftBox wrapper
1314- ** Structure** : Domain-driven design with components organized by feature
1415- ** Components** : Each component has entities, handlers, interfaces, repositories, routes, and schemas
@@ -22,6 +23,7 @@ Syft Space Server is a full-stack application with a FastAPI backend and Vue 3 f
2223 - ` shared/ ` - Common utilities (database, errors, logging)
2324
2425### Frontend Structure (` /frontend ` )
26+
2527- ** Framework** : Vue 3 with Composition API, TypeScript, Tailwind CSS
2628- ** UI Library** : shadcn/ui components (located in ` src/components/ui/ ` )
2729- ** State Management** : Pinia stores
@@ -32,6 +34,7 @@ Syft Space Server is a full-stack application with a FastAPI backend and Vue 3 f
3234## Development Commands
3335
3436### Backend Development
37+
3538``` bash
3639# Setup and run backend (from project root)
3740./run.sh
@@ -53,6 +56,7 @@ pytest # Run tests
5356```
5457
5558### Frontend Development
59+
5660``` bash
5761cd frontend
5862
@@ -80,13 +84,15 @@ bun run test:e2e # E2E tests against production build
8084## Development Patterns
8185
8286### Backend Patterns
87+
8388- Each component follows the same structure: entities, handlers, interfaces, repositories, routes, schemas
8489- Use SQLModel for database models
8590- Pydantic for request/response schemas
8691- FastAPI dependency injection for shared services
8792- Environment-based configuration via ` config.py `
8893
8994### Frontend Patterns
95+
9096- ** UI Components** : Always use shadcn/ui components. If needed component doesn't exist, install with ` npx shadcn-vue@latest add <component-name> `
9197- ** Icons** : Use lucide-vue-next icons
9298- ** Styling** : Tailwind CSS classes following existing patterns
@@ -99,10 +105,12 @@ bun run test:e2e # E2E tests against production build
99105 - State management in ` src/stores/ `
100106
101107### Code Style
108+
102109- ** Backend** : Black formatting (line-length 88), isort with black profile, type hints required
103110- ** Frontend** : Vue 3 Composition API with ` <script setup> ` , TypeScript, ESLint + Oxlint for linting
104111
105112## Server Configuration
113+
106114- Backend runs on configurable port (default 8080, set via ` SYFTBOX_ASSIGNED_PORT ` )
107115- Frontend served from ` /syft-space-server ` subpath
108116- CORS enabled for localhost:5173 (frontend dev server)
@@ -116,13 +124,15 @@ bun run test:e2e # E2E tests against production build
116124When integrating a backend API endpoint into the frontend:
117125
1181261 . ** Create API types** in ` frontend/src/api/types/index.ts ` :
127+
119128 ``` typescript
120129 export interface MyResponse {
121130 // Match the backend Pydantic schema
122131 }
123132 ```
124133
1251342 . ** Add API function** in ` frontend/src/api/endpoints/ ` :
135+
126136 ``` typescript
127137 export const myApi = {
128138 fetch : async (params ): Promise <MyResponse > => {
@@ -133,6 +143,7 @@ When integrating a backend API endpoint into the frontend:
133143 ```
134144
1351453 . ** Create composable** for complex logic in ` frontend/src/composables/ ` :
146+
136147 ``` typescript
137148 export function useMyFeature() {
138149 // Handle loading states, errors, data transformation
@@ -142,12 +153,14 @@ When integrating a backend API endpoint into the frontend:
1421534 . ** Update components** to use the API through stores or composables
143154
144155### Example: File Browser Integration
156+
145157- API types: ` frontend/src/api/types/index.ts `
146158- API endpoint: ` frontend/src/api/endpoints/datasets.ts `
147159- Composable: ` frontend/src/composables/useDatasetBrowser.ts `
148160- Component: ` frontend/src/components/FileExplorer.vue `
149161
150162## Important Notes
163+
151164- The frontend has its own CLAUDE.md with detailed UI component guidance
152165- Always run lint and typecheck commands after making changes
153166- Use bun for all frontend package operations
0 commit comments