alvaro/normogen
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

docs: reconcile documentation with reality (P3)

Browse source 
Make the project's documentation match the code and remove the sprawl. The docs
claimed Phase 2.8 (drug interactions) was 'planning/0%' and the backend '~91%
complete' — both wrong: 2.8 is implemented and live, plus the P0/P1 security
and test work is done. Five root CI/CD docs described a 'docker-build' CI job
that was removed; ~18 backend/ status snapshots and ~24 docs/implementation
duplicates cluttered the tree.

Deletions (85 files):
- Root: 4 stale CI/CD reports (CI-CD-{COMPLETION-REPORT,IMPLEMENTATION-SUMMARY,
  STATUS-REPORT,FINAL-STATUS}.md) — all describe the removed docker-build job.
- backend/: 18 phase/build/fix snapshots and code-dump .txt files.
- docs/: the 3 one-time reorg reports; ~17 docs/implementation duplicates and
  process artifacts; 4 stale docs/development CI docs + git snapshots;
  redundant deployment/testing files.
- thoughts/: STATUS.md (said Phase 2.4 in-progress), superseded phase notes and
  duplicative research inputs. tmp/ (928KB of CI debug logs, gitignored).

Moves (18 files):
- 9 genuine decision records -> docs/adr/ (Architecture Decision Records),
  date-prefixes stripped, with an index README.
- 8 historical-but-valuable phase plans/specs + the old CI-CD-FINAL-SOLUTION ->
  docs/archive/ (now-populated, with a README explaining it's superseded
  material). thoughts/ tree removed.

Rewrites (13 files) to match reality:
- Drop the fake '% complete' figures everywhere in favor of Implemented /
  In-Progress / Planned with concrete endpoint/feature lists.
- Phase 2.8 -> Implemented; add /api/interactions/* and /api/auth/{refresh,
  logout} to the endpoint lists; fix 'Rust 1.93' -> edition 2021.
- Add a Security section (token_version validation, hashed refresh-token
  persistence, fail-fast config, real-IP audit) and correct the test-coverage
  and deployment claims to reality.
- New canonical docs/development/CI-CD.md (4 jobs: format/clippy/build/test,
  mongo service, no docker-build + why).
- README, docs/README, product/{STATUS,ROADMAP,PROGRESS,README,introduction},
  implementation/README, development/README, testing/README, AI_AGENT_GUIDE,
  .cursorrules, .gooserules all updated.

Verified: greps for 'Phase 2.8 (Planning)', 'PLANNING (0%)', 'Rust 1.93',
'91%/10%/85% complete', and 'docker-build' return nothing outside docs/archive;
all internal doc links resolve; backend/src untouched (cargo build clean).
This commit is contained in:
goose 2026-06-27 16:02:16 -03:00
parent bd1b7c2925
commit 17efc4f656
119 changed files with 469 additions and 17801 deletions
Download patch file Download diff file Expand all files Collapse all files

312
thoughts/research/2026-02-14-monorepo-structure.md
View file

@ -1,312 +0,0 @@
# Monorepo Structure
## Repository Layout
```
normogen/ # Root Forgejo repository
├── backend/ # Rust backend (Axum + MongoDB)
│ ├── src/ # Source code
│ │ ├── main.rs # Entry point
│ │ ├── auth/ # Authentication
│ │ │ ├── mod.rs
│ │ │ ├── jwt_service.rs
│ │ │ ├── claims.rs
│ │ │ └── middleware.rs
│ │ ├── api/ # API endpoints
│ │ │ ├── mod.rs
│ │ │ ├── users.rs
│ │ │ ├── families.rs
│ │ │ ├── profiles.rs
│ │ │ ├── health_data.rs
│ │ │ ├── lab_results.rs
│ │ │ ├── medications.rs
│ │ │ ├── appointments.rs
│ │ │ └── shares.rs
│ │ ├── db/ # Database
│ │ │ ├── mod.rs
│ │ │ ├── mongo.rs
│ │ │ ├── models.rs
│ │ │ └── repositories.rs
│ │ ├── config/ # Configuration
│ │ │ ├── mod.rs
│ │ │ ├── app.rs
│ │ │ ├── jwt.rs
│ │ │ ├── mongo.rs
│ │ │ └── cors.rs
│ │ ├── middleware/ # Middleware
│ │ │ ├── mod.rs
│ │ │ ├── auth.rs
│ │ │ ├── logging.rs
│ │ │ └── rate_limit.rs
│ │ ├── utils/ # Utilities
│ │ │ ├── mod.rs
│ │ │ ├── crypto.rs
│ │ │ └── validation.rs
│ │ └── error.rs # Error types
│ ├── docker/
│ │ ├── Dockerfile # Production build
│ │ └── Dockerfile.dev # Development build
│ ├── config/
│ │ ├── .env.example # Environment template
│ │ └── defaults.env # Default values
│ ├── k8s/ # Kubernetes manifests (future)
│ │ ├── base/
│ │ └── overlays/
│ ├── Cargo.toml # Dependencies
│ ├── Cargo.lock # Lock file
│ ├── docker-compose.yml # Production deployment
│ ├── docker-compose.dev.yml # Development deployment
│ └── README.md # Backend README
│
├── mobile/ # React Native (iOS + Android)
│ ├── src/ # Source code
│ │ ├── components/ # Reusable components
│ │ │ ├── common/
│ │ │ ├── health/
│ │ │ ├── lab/
│ │ │ └── medication/
│ │ ├── screens/ # Screen components
│ │ │ ├── auth/
│ │ │ ├── home/
│ │ │ ├── family/
│ │ │ ├── profile/
│ │ │ ├── health/
│ │ │ ├── lab/
│ │ │ └── settings/
│ │ ├── navigation/ # Navigation config
│ │ │ ├── AppNavigator.tsx
│ │ │ ├── AuthNavigator.tsx
│ │ │ └── LinkingConfiguration.tsx
│ │ ├── store/ # Redux store
│ │ │ ├── slices/
│ │ │ │ ├── authSlice.ts
│ │ │ │ ├── userSlice.ts
│ │ │ │ ├── familySlice.ts
│ │ │ │ ├── profileSlice.ts
│ │ │ │ └── healthDataSlice.ts
│ │ │ └── store.ts
│ │ ├── services/ # API services
│ │ │ ├── api.ts # Axios client
│ │ │ ├── authService.ts
│ │ │ ├── userService.ts
│ │ │ └── healthDataService.ts
│ │ ├── utils/ # Utilities
│ │ │ ├── encryption.ts # Client-side encryption
│ │ │ ├── validation.ts
│ │ │ └── constants.ts
│ │ ├── hooks/ # Custom hooks
│ │ │ ├── useAuth.ts
│ │ │ └── useEncryptedStorage.ts
│ │ ├── types/ # TypeScript types
│ │ │ └── index.ts
│ │ └── assets/ # Images, fonts
│ ├── android/ # Android native code
│ │ ├── app/
│ │ └── build.gradle
│ ├── ios/ # iOS native code
│ │ ├── Normogen
│ │ └── Podfile
│ ├── package.json
│ ├── tsconfig.json
│ ├── App.tsx # Entry component
│ ├── README.md
│ └── .env.example
│
├── web/ # React web app
│ ├── src/ # Source code
│ │ ├── components/ # Reusable components
│ │ │ ├── common/
│ │ │ ├── health/
│ │ │ ├── lab/
│ │ │ └── charts/
│ │ ├── pages/ # Page components
│ │ │ ├── auth/
│ │ │ ├── home/
│ │ │ ├── family/
│ │ │ ├── profile/
│ │ │ ├── health/
│ │ │ ├── lab/
│ │ │ └── settings/
│ │ ├── store/ # Redux store (shared with mobile)
│ │ │ ├── slices/
│ │ │ └── store.ts
│ │ ├── services/ # API services (shared with mobile)
│ │ │ ├── api.ts
│ │ │ └── ...
│ │ ├── utils/ # Utilities (shared with mobile)
│ │ │ ├── encryption.ts
│ │ │ └── ...
│ │ ├── hooks/ # Custom hooks
│ │ │ └── ...
│ │ ├── types/ # TypeScript types (shared)
│ │ │ └── index.ts
│ │ ├── styles/ # CSS/global styles
│ │ │ └── global.css
│ │ └── App.tsx
│ ├── package.json
│ ├── tsconfig.json
│ ├── index.html
│ ├── vite.config.ts # Vite config
│ └── README.md
│
├── shared/ # Shared TypeScript code
│ ├── src/
│ │ ├── types/ # Shared type definitions
│ │ │ ├── user.ts
│ │ │ ├── family.ts
│ │ │ ├── profile.ts
│ │ │ ├── healthData.ts
│ │ │ ├── labResults.ts
│ │ │ ├── medications.ts
│ │ │ ├── appointments.ts
│ │ │ ├── shares.ts
│ │ │ └── api.ts
│ │ ├── validation/ # Zod schemas
│ │ │ ├── user.ts
│ │ │ ├── family.ts
│ │ │ └── healthData.ts
│ │ ├── encryption/ # Encryption utilities
│ │ │ ├── crypto.ts
│ │ │ └── keyDerivation.ts
│ │ ├── api/ # Shared API client
│ │ │ ├── client.ts
│ │ │ └── endpoints.ts
│ │ └── constants/ # Shared constants
│ │ ├── routes.ts
│ │ └── config.ts
│ ├── package.json
│ ├── tsconfig.json
│ └── README.md
│
├── thoughts/ # Research & design docs
│ ├── research/
│ │ ├── 2026-02-14-rust-framework-comparison.md
│ │ ├── 2026-02-14-rust-framework-performance-research.md
│ │ ├── 2026-02-14-performance-findings.md
│ │ ├── 2026-02-14-research-summary.md
│ │ ├── 2026-02-14-frontend-mobile-research.md
│ │ ├── 2026-02-14-frontend-decision-summary.md
│ │ ├── 2026-02-14-state-management-research.md
│ │ ├── 2026-02-14-state-management-decision.md
│ │ ├── 2026-02-14-jwt-authentication-research.md
│ │ ├── 2026-02-14-jwt-authentication-decision.md
│ │ ├── 2026-02-14-mongodb-schema-design-research.md
│ │ ├── 2026-02-14-mongodb-schema-decision.md
│ │ ├── 2026-02-14-backend-deployment-constraints.md
│ │ └── 2026-02-14-monorepo-structure.md
│ └── research/
│
├── .gitignore # Root gitignore
├── README.md # Root README
├── docker-compose.root.yml # Run all services (optional)
└── .forgejo/ # Forgejo CI/CD workflows
└── workflows/
├── backend-build.yml
├── mobile-build.yml
└── web-build.yml
```
## Directory Creation Commands
```bash
# Create root directories
mkdir -p backend/{src/{auth,api,db,config,middleware,utils},docker,config,k8s/base,k8s/overlays/homelab,k8s/overlays/production}
mkdir -p mobile/{src/{components/{common,health,lab,medication},screens/{auth,home,family,profile,health,lab,settings},navigation,store/slices,services,utils,hooks,types,assets},android,ios}
mkdir -p web/{src/{components/{common,health,lab,charts},pages/{auth,home,family,profile,health,lab,settings},store/slices,services,utils,hooks,types,styles}}
mkdir -p shared/src/{types,validation,encryption,api,constants}
mkdir -p thoughts/research
mkdir -p .forgejo/workflows
# Create placeholder files
touch backend/src/{main.rs,auth/mod.rs,api/mod.rs,db/mod.rs,config/mod.rs,middleware/mod.rs,utils/mod.rs,error.rs}
touch mobile/src/{App.tsx,navigation/AppNavigator.tsx,store/store.ts,services/api.ts,utils/encryption.ts}
touch web/src/{App.tsx,store/store.ts,services/api.ts,utils/encryption.ts}
touch shared/src/{types/index.ts,validation/index.ts,encryption/crypto.ts,api/client.ts}
```
## Git Strategy
### Branch Strategy
- `main`: Production releases
- `develop`: Development integration
- `feature/backend-*`: Backend features
- `feature/mobile-*`: Mobile features
- `feature/web-*`: Web features
- `feature/shared-*`: Shared code features
### Commit Message Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
Types: feat, fix, docs, style, refactor, test, chore
Scopes: backend, mobile, web, shared, ci/cd
Examples:
- `feat(backend): Implement JWT authentication with refresh tokens`
- `fix(mobile): Resolve encryption key storage issue`
- `docs(shared): Update API type definitions`
- `chore(ci/cd): Add Forgejo workflow for backend builds`
## Shared Code Management
### TypeScript Package
The `shared/` directory contains TypeScript code shared between mobile and web:
- Type definitions (API models)
- Validation schemas (Zod)
- Encryption utilities
- API client
- Constants
### Usage in Mobile/Web
```json
// mobile/package.json and web/package.json
{
"dependencies": {
"shared": "file:../shared"
}
}
```
### Watch Mode for Development
```bash
# In shared/ directory
npm run watch # Watch and rebuild on changes
# In mobile/ and web/ directories
# Changes to shared/ are automatically picked up
```
## Next Steps
1. **Initialize Monorepo Structure**
- Create all directories
- Create placeholder files
- Update root .gitignore
2. **Backend Initialization**
- Initialize Rust project (backend/)
- Setup Cargo.toml
- Create docker-compose files
- Create Dockerfiles
3. **Shared Code Setup**
- Initialize TypeScript project (shared/)
- Setup type definitions
- Setup Zod validation schemas
- Setup encryption utilities
4. **Mobile Setup** (Phase 3)
- Initialize React Native project
- Setup Redux Toolkit
- Setup navigation
5. **Web Setup** (Phase 3)
- Initialize React project
- Setup Redux Toolkit
- Setup routing