FileAtlas

Inspiration

As former executive board members of the Japanese Student Association (JSA) at Cal Poly — a club with 100+ members — we experienced firsthand how chaotic a shared Google Drive becomes over time. Event photos dumped in the wrong folder, budget spreadsheets buried three levels deep, meeting minutes nobody could find. When new officers took over each year, they inherited a mess with no context. We built FileAtlas to solve the exact frustration we lived through, and to help every college club that faces the same problem.

What it does

FileAtlas sits on top of Google Drive and uses Gemini AI to bring order to the chaos. When a club first connects their Drive, the AI analyzes the existing file structure and proposes 2–3 clean folder architectures (preserve existing, reorganize, or build fresh). Admins can review, edit, and activate a structure. From there, newly uploaded files are automatically sorted into the right folder with AI-generated confidence scores, tags, and one-sentence summaries. Batch processing lets users upload many files at once and let the AI organize everything. Smart search handles natural language queries like "find the quarter report for winter 2024." Role-based access control (Admin, Mod, Member) ensures sensitive files are only visible to the right people.

How we built it

We used Kiro's spec-driven development workflow to structure the entire project before writing code. We started with a requirements document (50 formal requirements), then a technical design document (14 database models, 60+ API endpoints, Gemini prompt strategies), and finally an implementation task list with 150+ subtasks. Two developers worked in parallel — Cameron on the React frontend and Jonathan on the Express backend — coordinated through Kiro's steering docs that defined file ownership, code conventions, and API contracts. The backend uses Node.js, Express, TypeScript, Prisma, and PostgreSQL. The frontend uses React 18, TypeScript, Tailwind CSS, and shadcn/ui. AI features are powered by Google's Gemini API (1.5 Pro for architecture proposals, 1.5 Flash for upload routing and tagging). We used Kiro agent hooks to auto-format code on save and auto-commit/push after each task, which kept both developers in sync throughout the build.

Challenges we ran into

Parallel development was the biggest challenge. Two developers using AI agents simultaneously on the same codebase could easily produce incompatible code. We solved this by splitting work strictly by directory (client/ vs server/) and using Kiro steering docs as a shared contract. We also hit issues with TypeScript type declarations not being picked up by ts-node at runtime, which required casting fixes across multiple files. The git hooks created an unexpected feedback loop where post-task hooks would fire on every subtask completion, generating dozens of micro-commits — we had to disable and re-enable them strategically. Wiring the frontend to the backend revealed response shape mismatches (the server wrapped responses in {user: ...} but the client expected the object directly), which required careful debugging of the API layer.

Accomplishments that we're proud of

We built a full-stack application with 14 database models, 60+ API endpoints, 14 service classes, and a complete React frontend in 13 hours with two developers. The spec-driven approach meant zero merge conflicts across the entire build. We have 22 property-based tests covering correctness properties like role hierarchy enforcement, session expiry, placement threshold consistency, and duplicate detection. The AI upload flow — where files get automatically sorted, tagged, and summarized — works end-to-end and demonstrates a genuinely useful product that we wish we had when running JSA.

What we learned

Spec-driven development is dramatically more effective than vibe coding for structural work. Having the database schema, API surface, and component interfaces defined upfront eliminated the back-and-forth of "what should this endpoint return?" Steering docs were the single most impactful Kiro feature for team coordination — they ensured every AI session on both machines followed the same conventions. We also learned that agent hooks need careful design to avoid feedback loops, and that the best hackathon strategy is to get the core data flow working first (auth → database → API → UI) before adding AI features on top.

What's next for FileAtlas

We plan to bring FileAtlas to production with a hosted PostgreSQL database and real Gemini API integration replacing the mocked AI responses. Full Google Drive sync with webhook-based change detection will keep the metadata store accurate as files change outside of FileAtlas. We want to add user safety features (rate limiting, input sanitization, CSRF protection), a mobile-responsive UI, and eventually open it up as a tool any college club can sign up for. The long-term vision is an AI file assistant that doesn't just organize — it learns your club's patterns and gets smarter over time.

Built With

• agent-hooks
• docker-apis:-google-gemini-api-(1.5-pro-+-1.5-flash)
• express.js
• fast-check-(property-based-testing)
• git
• google-drive-api-v3
• google-oauth-2.0-testing:-vitest
• languages:-typescript
• lucide-icons-backend:-node.js
• multer-database:-postgresql-16
• npm
• passport.js
• prisma-orm
• react-router-v6
• react-testing-library-dev-tools:-kiro-(spec-driven-development
• shadcn/ui
• sql-frontend:-react-18
• steering-docs)
• tailwind-css
• tanstack-query
• vite
• zod